portable-agent-layer 0.97.0 → 0.99.0

package/src/tools/agent/project.ts

@@ -28,6 +28,7 @@ import {
 } from "../../hooks/lib/projects";
 import { isServesKind, SERVES_KINDS, setServes } from "../../hooks/lib/serves";
 import { group, type Leaf, leaf, runCommand, UsageError } from "../lib/command";
+import { decisionRow, emitHistoryRow, registrationRow } from "../lib/project-history";
 import {
   archiveLine,
   completeIsc,
@@ -169,6 +170,7 @@ function cmdCreate(given: string | undefined, values: CreateValues): undefined {
     ...(values["serves-note"] ? { serves_note: values["serves-note"] } : {}),
   };
   writeProject(project);
+  emitHistoryRow(registrationRow(project));
   ok({ created: true, project });
 }
 
@@ -258,11 +260,13 @@ function addDecision(name: string, decision: string, rationale: string): undefin
   const what = nonBlank(decision, "<decision>");
   const why = nonBlank(rationale, "<rationale...>");
   const p = requireProject(name);
-  const date = new Date().toISOString().slice(0, 10);
+  const ts = now();
+  const date = ts.slice(0, 10);
   const line = `- ${date}: ${what} (${why})`;
   p.decisions = p.decisions ? `${p.decisions}\n${line}` : line;
-  p.updated = now();
+  p.updated = ts;
   writeProject(p);
+  emitHistoryRow({ ...decisionRow(name, date, `${what} (${why})`), ts });
   ok({ updated: true, name });
 }
 
@@ -434,6 +438,7 @@ function cmdAddIsc(name: string, text: string): undefined {
   p.criteria = current ? `${current.trimEnd()}\n${newLine}` : newLine;
   p.updated = now();
   writeProject(p);
+  logCommitment(name, id, "opened", "cli");
   ok({
     added: true,
     id,

package/src/tools/knowledge/lib.ts

@@ -31,7 +31,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { resolve } from "node:path";
-import { logEntityFirstSeen } from "../../hooks/lib/entity-events";
+import { logEntityFirstSeen, type SeenEntity } from "../../hooks/lib/entity-events";
 import { ensureDir, paths } from "../../hooks/lib/paths";
 
 // --- Constants --------------------------------------------------------------
@@ -411,6 +411,15 @@ export function exists(domain: Domain, slug: string, rootDir?: string): boolean
   return existsSync(entityPath(domain, slug, rootDir));
 }
 
+export function seenEntity(entity: Entity): SeenEntity {
+  return {
+    domain: entity.domain,
+    slug: entity.slug,
+    entityType: entity.frontmatter.type,
+    name: entity.frontmatter.title,
+  };
+}
+
 export function save(entity: Entity, rootDir?: string): void {
   const p = entityPath(entity.domain, entity.slug, rootDir);
   const firstSeenInTheStore = !rootDir && !existsSync(p);
@@ -418,7 +427,7 @@ export function save(entity: Entity, rootDir?: string): void {
   writeFileSync(tmp, serialize(entity), "utf-8");
   renameSync(tmp, p);
   if (firstSeenInTheStore) {
-    logEntityFirstSeen(entity.domain, entity.frontmatter.type, entity.frontmatter.title);
+    logEntityFirstSeen(seenEntity(entity));
   }
 }
 

package/src/tools/lib/backfill/entities.ts

@@ -0,0 +1,31 @@
+/**
+ * Every entity in the knowledge store, first seen when it was created. The
+ * live event shares its id, so an entity already logged is skipped.
+ */
+
+import { entityEventId, logEntityFirstSeen } from "../../../hooks/lib/entity-events";
+import { type Entity, list, seenEntity } from "../../knowledge/lib";
+import { emitUnseen } from "./rows";
+
+interface EntityRow {
+  entity: Entity;
+  ts: string;
+}
+
+function emitEntity(row: EntityRow): void {
+  logEntityFirstSeen(seenEntity(row.entity), {
+    ts: row.ts,
+    session: null,
+    channel: null,
+    cwd: "",
+    attribution: { machine: "unknown", actor: "unknown", runtime: "unknown" },
+  });
+}
+
+/** Appends the entities not yet logged and returns how many. */
+export function backfillEntities(known: Set<string>, since?: string): number {
+  const rows = list()
+    .filter((entity) => entity.frontmatter.created)
+    .map((entity) => ({ entity, ts: entity.frontmatter.created }));
+  return emitUnseen(rows, (row) => entityEventId(row.entity), emitEntity, known, since);
+}

package/src/tools/lib/backfill/git.ts

@@ -0,0 +1,184 @@
+/**
+ * Every commit that still exists in a registered project's repository, as a
+ * commit event whose id is its hash. Names, emails and the subject are text,
+ * so they go to the content store; the event keeps counts and flags.
+ */
+
+import { spawnSync } from "node:child_process";
+import { appendEvent } from "../../../hooks/lib/events";
+import { PAL_REPO_URL } from "../../../hooks/lib/remote";
+
+const RECORD = "\x1e";
+const FIELD = "\x1f";
+const FORMAT = [
+  "%H",
+  "%aI",
+  "%cI",
+  "%an",
+  "%ae",
+  "%cn",
+  "%ce",
+  "%D",
+  "%P",
+  "%s",
+  "%b",
+  "",
+]
+  .join(FIELD)
+  .replace(/^/, RECORD);
+const AI_CO_AUTHOR = new RegExp(
+  String.raw`noreply@anthropic\.com|${PAL_REPO_URL.replace(/[.]/g, String.raw`\.`)}|copilot|cursor|openai|codex|gemini`,
+  "i"
+);
+const CONVENTIONAL = /^(\w+)(\([^)]*\))?(!)?:/;
+
+interface Commit {
+  hash: string;
+  authoredAt: string;
+  committedAt: string;
+  author: string;
+  authorEmail: string;
+  committer: string;
+  committerEmail: string;
+  subject: string;
+  files: number;
+  added: number;
+  deleted: number;
+  commitType: string | null;
+  breaking: boolean;
+  revert: boolean;
+  merge: boolean;
+  tags: string[];
+  coAuthors: number;
+  aiCoAuthored: boolean;
+}
+
+function gitLog(repo: string, since: string | undefined): string | null {
+  const args = [
+    "-C",
+    repo,
+    "log",
+    "--branches",
+    "--tags",
+    "--remotes",
+    "--numstat",
+    `--format=${FORMAT}`,
+  ];
+  if (since) args.push(`--since=${since}`);
+  const result = spawnSync("git", args, {
+    encoding: "utf-8",
+    maxBuffer: 256 * 1024 * 1024,
+  });
+  return result.status === 0 ? result.stdout : null;
+}
+
+function numstatOf(text: string) {
+  const rows = text
+    .split("\n")
+    .map((line) => line.split("\t"))
+    .filter((cells) => cells.length === 3);
+  const count = (cell: string) => (cell === "-" ? 0 : Number(cell));
+  return {
+    files: rows.length,
+    added: rows.reduce((sum, [added]) => sum + count(added), 0),
+    deleted: rows.reduce((sum, [, deleted]) => sum + count(deleted), 0),
+  };
+}
+
+function coAuthorLines(body: string): string[] {
+  return body.split("\n").filter((line) => /^co-authored[- ]by\b/i.test(line.trim()));
+}
+
+function tagsOf(refs: string): string[] {
+  return refs
+    .split(", ")
+    .filter((ref) => ref.startsWith("tag: "))
+    .map((ref) => ref.slice("tag: ".length));
+}
+
+function commitOf(record: string): Commit | null {
+  const [hash, aI, cI, an, ae, cn, ce, refs, parents, subject, body, numstat] =
+    record.split(FIELD);
+  if (!hash || !aI || !cI) return null;
+  const conventional = CONVENTIONAL.exec(subject ?? "");
+  const coAuthors = coAuthorLines(body ?? "");
+  return {
+    hash,
+    authoredAt: new Date(aI).toISOString(),
+    committedAt: new Date(cI).toISOString(),
+    author: an ?? "",
+    authorEmail: ae ?? "",
+    committer: cn ?? "",
+    committerEmail: ce ?? "",
+    subject: subject ?? "",
+    ...numstatOf(numstat ?? ""),
+    commitType: conventional?.[1] ?? null,
+    breaking: !!conventional?.[3] || /^BREAKING CHANGE:/m.test(body ?? ""),
+    revert: conventional?.[1] === "revert" || (subject ?? "").startsWith("Revert "),
+    merge: (parents ?? "").trim().split(" ").length > 1,
+    tags: tagsOf(refs ?? ""),
+    coAuthors: coAuthors.length,
+    aiCoAuthored: coAuthors.some((line) => AI_CO_AUTHOR.test(line)),
+  };
+}
+
+function readCommits(repo: string, since?: string): Commit[] {
+  const log = gitLog(repo, since);
+  if (log === null) return [];
+  return log
+    .split(RECORD)
+    .map(commitOf)
+    .filter((commit): commit is Commit => commit !== null);
+}
+
+const commitEventId = (hash: string) => `git:${hash}`;
+
+function emitCommit(repo: string, commit: Commit): void {
+  appendEvent(
+    "commit",
+    {
+      hash: commit.hash,
+      committedAt: commit.committedAt,
+      files: commit.files,
+      added: commit.added,
+      deleted: commit.deleted,
+      commitType: commit.commitType,
+      breaking: commit.breaking,
+      revert: commit.revert,
+      merge: commit.merge,
+      tags: commit.tags,
+      coAuthors: commit.coAuthors,
+      aiCoAuthored: commit.aiCoAuthored,
+    },
+    {
+      id: commitEventId(commit.hash),
+      ts: commit.authoredAt,
+      session: null,
+      runtime: "git",
+      channel: null,
+      cwd: repo,
+      content: {
+        author: commit.author,
+        authorEmail: commit.authorEmail,
+        committer: commit.committer,
+        committerEmail: commit.committerEmail,
+        subject: commit.subject,
+      },
+    }
+  );
+}
+
+/** Appends the commits not yet logged and returns how many. */
+export function backfillGit(repos: string[], known: Set<string>, since?: string): number {
+  let emitted = 0;
+  for (const repo of repos) {
+    for (const commit of readCommits(repo, since)) {
+      const id = commitEventId(commit.hash);
+      if (known.has(id)) continue;
+      known.add(id);
+      emitCommit(repo, commit);
+      emitted++;
+    }
+  }
+  return emitted;
+}

package/src/tools/lib/backfill/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Everything that still exists, read into the event log once. Every event's id
+ * comes from its source's own id, so a second run appends nothing.
+ */
+
+import { loggedEventIds } from "../../../hooks/lib/events";
+import { readAllProjects } from "../../../hooks/lib/projects";
+import { eventLogEnabled } from "../../../hooks/lib/settings";
+import { backfillEntities } from "./entities";
+import { backfillGit } from "./git";
+import { backfillLedger } from "./ledger";
+import { backfillProjects } from "./projects";
+import { backfillPromises } from "./promises";
+import { backfillRatings } from "./ratings";
+import { backfillSessions } from "./sessions";
+import { backfillTurns } from "./turns";
+
+function projectRepos(): string[] {
+  const paths = readAllProjects().flatMap((project) =>
+    project.path ? [project.path] : []
+  );
+  return [...new Set(paths)];
+}
+
+export function backfillEvents(since?: string): Record<string, number> {
+  if (!eventLogEnabled()) return {};
+  const known = loggedEventIds();
+  return {
+    git: backfillGit(projectRepos(), known, since),
+    sessions: backfillSessions(since),
+    turns: backfillTurns(known, since),
+    ratings: backfillRatings(known, since),
+    ledger: backfillLedger(known, since),
+    projects: backfillProjects(known, since),
+    promises: backfillPromises(known, since),
+    entities: backfillEntities(known, since),
+  };
+}

package/src/tools/lib/backfill/ledger.ts

@@ -0,0 +1,28 @@
+/**
+ * Every ledger entry, as the action event it would have streamed. Rows the
+ * test suite leaked into the real ledger before it was sandboxed are left out.
+ */
+
+import {
+  actionEventId,
+  type LedgerEntry,
+  logActionEvent,
+} from "../../../hooks/lib/ledger";
+import { readLedger } from "../../ledger/query";
+import { emitUnseen, recordedAttribution } from "./rows";
+
+const SUITE_SANDBOXED_AT = "2026-09-23T14:35:01.000Z";
+
+function leakedFromTestSuite(entry: LedgerEntry): boolean {
+  return entry.command === "rm -rf /" && entry.ts < SUITE_SANDBOXED_AT;
+}
+
+function emitAction(entry: LedgerEntry): void {
+  logActionEvent(entry, recordedAttribution(entry));
+}
+
+/** Appends the ledger entries not yet logged and returns how many. */
+export function backfillLedger(known: Set<string>, since?: string): number {
+  const entries = readLedger().filter((entry) => !leakedFromTestSuite(entry));
+  return emitUnseen(entries, actionEventId, emitAction, known, since);
+}

package/src/tools/lib/backfill/projects.ts

@@ -0,0 +1,40 @@
+/**
+ * What each project's ISA still records about its own history. An ISC's
+ * opening was never dated, so it cannot be backfilled; a close already
+ * streamed live as a commitment is not logged twice.
+ */
+
+import { eventsSince } from "../../../hooks/lib/events";
+import { readAllProjects } from "../../../hooks/lib/projects";
+import {
+  closedIscRows,
+  decisionRows,
+  emitHistoryRow,
+  type HistoryRow,
+  registrationRow,
+} from "../project-history";
+import { emitUnseen, recordedAttribution } from "./rows";
+
+const commitmentKey = (fields: Record<string, unknown>) =>
+  `${fields.iscProject}:${fields.isc}:${fields.outcome}`;
+
+function liveCommitments(): Set<string> {
+  return new Set(eventsSince("commitment", new Date(0)).map(commitmentKey));
+}
+
+function emitHistory(row: HistoryRow): void {
+  emitHistoryRow(row, recordedAttribution(row));
+}
+
+/** Appends the project history not yet logged and returns how many events. */
+export function backfillProjects(known: Set<string>, since?: string): number {
+  const live = liveCommitments();
+  const rows = readAllProjects()
+    .flatMap((project) => [
+      registrationRow(project),
+      ...closedIscRows(project),
+      ...decisionRows(project),
+    ])
+    .filter((row) => row.type !== "commitment" || !live.has(commitmentKey(row.fields)));
+  return emitUnseen(rows, (row) => row.id, emitHistory, known, since);
+}

package/src/tools/lib/backfill/promises.ts

@@ -0,0 +1,91 @@
+/**
+ * The promises the Discord bot nags about, from its store: each one made, and
+ * each one closed as done or dropped. The title is text, so it goes to the
+ * content store.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { appendEvent } from "../../../hooks/lib/events";
+import { paths } from "../../../hooks/lib/paths";
+import { emitUnseen } from "./rows";
+
+interface StoredPromise {
+  id: number;
+  title: string;
+  due: string;
+  status: "open" | "done" | "dropped";
+  createdAt: string;
+  closedAt?: string;
+  project?: string;
+  snoozes: number;
+  nagCount: number;
+}
+
+interface PromiseRow {
+  id: string;
+  ts: string;
+  project: string | null;
+  fields: Record<string, unknown>;
+  title: string;
+}
+
+const secondsBetween = (from: string, to: string) =>
+  Math.round((Date.parse(to) - Date.parse(from)) / 1000);
+
+function readPromises(): StoredPromise[] {
+  const file = resolve(paths.memory(), "commitments.json");
+  if (!existsSync(file)) return [];
+  try {
+    return JSON.parse(readFileSync(file, "utf-8")).items ?? [];
+  } catch {
+    return [];
+  }
+}
+
+function made(promise: StoredPromise): PromiseRow {
+  return {
+    id: `promise:${promise.id}:${promise.createdAt}:made`,
+    ts: promise.createdAt,
+    project: promise.project ?? null,
+    fields: { change: "made", dueInSec: secondsBetween(promise.createdAt, promise.due) },
+    title: promise.title,
+  };
+}
+
+function closed(promise: StoredPromise): PromiseRow[] {
+  if (promise.status === "open" || !promise.closedAt) return [];
+  return [
+    {
+      id: `promise:${promise.id}:${promise.createdAt}:${promise.status}`,
+      ts: promise.closedAt,
+      project: promise.project ?? null,
+      fields: {
+        change: promise.status,
+        lateSec: secondsBetween(promise.due, promise.closedAt),
+        snoozes: promise.snoozes,
+        nags: promise.nagCount,
+      },
+      title: promise.title,
+    },
+  ];
+}
+
+function emitPromise(row: PromiseRow): void {
+  appendEvent("promise", row.fields, {
+    id: row.id,
+    ts: row.ts,
+    session: null,
+    channel: null,
+    cwd: "",
+    project: row.project,
+    attribution: { machine: "unknown", actor: "unknown", runtime: "unknown" },
+    content: { title: row.title },
+  });
+}
+
+/** Appends the promises not yet logged and returns how many events. */
+export function backfillPromises(known: Set<string>, since?: string): number {
+  const rows = readPromises().flatMap((promise) => [made(promise), ...closed(promise)]);
+  return emitUnseen(rows, (row) => row.id, emitPromise, known, since);
+}

package/src/tools/lib/backfill/ratings.ts

@@ -0,0 +1,21 @@
+/**
+ * Every rating in the signals file, as a rating event. The rated context and
+ * the reply preview are text, so they go to the content store.
+ */
+
+import {
+  logRatingEvent,
+  type RatingSignal,
+  ratingEventId,
+  readRatings,
+} from "../../../hooks/lib/signals";
+import { emitUnseen, recordedAttribution } from "./rows";
+
+function emitRating(row: RatingSignal): void {
+  logRatingEvent(row, { cwd: "", attribution: recordedAttribution(row) });
+}
+
+/** Appends the ratings not yet logged and returns how many. */
+export function backfillRatings(known: Set<string>, since?: string): number {
+  return emitUnseen(readRatings(), ratingEventId, emitRating, known, since);
+}

package/src/tools/lib/backfill/rows.ts

@@ -0,0 +1,33 @@
+import type { RecordAttribution } from "../../../hooks/lib/actor";
+
+export type AttributedRow = Partial<RecordAttribution> & { ts: string };
+
+/** The origin a row was written with; a field it never carried is unknown, not this machine's. */
+export function recordedAttribution(row: AttributedRow): Partial<RecordAttribution> {
+  return {
+    machine: row.machine ?? "unknown",
+    actor: row.actor ?? "unknown",
+    runtime: row.runtime ?? "unknown",
+    ...(row.authority && { authority: row.authority }),
+  };
+}
+
+/** Emits each row whose id is not logged yet and that falls on or after `since`; returns how many. */
+export function emitUnseen<Row extends AttributedRow>(
+  rows: Row[],
+  idOf: (row: Row) => string,
+  emit: (row: Row, id: string) => void,
+  known: Set<string>,
+  since?: string
+): number {
+  const from = new Date(since ?? 0).toISOString();
+  let emitted = 0;
+  for (const row of rows) {
+    const id = idOf(row);
+    if (known.has(id) || row.ts < from) continue;
+    known.add(id);
+    emit(row, id);
+    emitted++;
+  }
+  return emitted;
+}

package/src/tools/lib/backfill/sessions.ts

@@ -0,0 +1,56 @@
+/**
+ * Every session PAL still has a record of, as the session_end it would have
+ * logged. A record is the session's last known state, so it carries no reason,
+ * duration or turn count; its name, summary and handoff are text and go to the
+ * content store.
+ */
+
+import { appendEvent, eventsSince } from "../../../hooks/lib/events";
+import { readSessionHistory, type SessionRecord } from "../../../hooks/lib/work-tracking";
+
+const sessionEventId = (sessionId: string) => `session:${sessionId}`;
+
+function endedSessions(): Set<string> {
+  return new Set(
+    eventsSince("session_end", new Date(0)).flatMap((e) => (e.session ? [e.session] : []))
+  );
+}
+
+function emitSession(record: SessionRecord): void {
+  appendEvent(
+    "session_end",
+    {
+      reason: "backfill",
+      durationSec: null,
+      turns: null,
+      messages: record.messageCount,
+      status: record.status,
+    },
+    {
+      id: sessionEventId(record.sessionId),
+      ts: record.ts,
+      session: record.sessionId,
+      runtime: "unknown",
+      channel: null,
+      cwd: record.cwd,
+      content: {
+        name: record.name,
+        summary: record.summary,
+        handoff: record.handoff,
+        artifacts: record.artifacts,
+      },
+    }
+  );
+}
+
+/** Appends the sessions with no session_end yet and returns how many. */
+export function backfillSessions(since?: string): number {
+  const ended = endedSessions();
+  const fresh = readSessionHistory().filter(
+    (record) =>
+      !ended.has(record.sessionId) &&
+      (!since || record.ts >= new Date(since).toISOString())
+  );
+  for (const record of fresh) emitSession(record);
+  return fresh.length;
+}

package/src/tools/lib/backfill/turns.ts

@@ -0,0 +1,32 @@
+/**
+ * Every turn measured before turns streamed into the event log. A row keeps
+ * the machine, actor and runtime it was written with, since an imported file
+ * holds other machines' rows too.
+ */
+
+import { appendEvent } from "../../../hooks/lib/events";
+import {
+  legacyTurnId,
+  legacyTurns,
+  type TurnEvent,
+} from "../../../hooks/lib/interaction";
+import { type AttributedRow, emitUnseen, recordedAttribution } from "./rows";
+
+type LegacyTurn = TurnEvent & AttributedRow;
+
+function emitTurn(turn: LegacyTurn, id: string): void {
+  const { ts, session, channel, ...fields } = turn;
+  appendEvent("turn", fields, {
+    id,
+    ts,
+    session,
+    channel: channel ?? null,
+    cwd: "",
+    attribution: recordedAttribution(turn),
+  });
+}
+
+/** Appends the legacy turns not yet logged and returns how many. */
+export function backfillTurns(known: Set<string>, since?: string): number {
+  return emitUnseen(legacyTurns() as LegacyTurn[], legacyTurnId, emitTurn, known, since);
+}