@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/feed/activity.js

@@ -1,22 +1,3 @@
-/**
- * Activity log -- an append-only, per-session stream of agent-semantic events
- * (plan created, PR opened, worktree created, sub-agent spawned, file edited).
- *
- * This is the counterpart to the feed block store: the block store is
- * last-writer-wins STATE ("this agent is waiting on you"), while the activity
- * log is an append-only EVENT stream ("this agent did X at T"). Together they
- * let `agents feed` show both open decisions and a running activity lane
- * without ever re-parsing session transcripts -- events are emitted at hook
- * time by `11-activity-log.py` and read back by tailing the log.
- *
- * Layout: <activityDir>/<sessionId>.jsonl  (one append-only file per session)
- *   Each line is one {@link ActivityEvent}. Files are keyed by session so a
- *   plain O_APPEND write is race-free (a session has a single writer process).
- *
- * Event tiers:
- *   - `milestone` -- recognizable deliverables, always surfaced individually.
- *   - `activity`  -- routine work (file edits), collapsed to counts by readers.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -27,8 +8,7 @@ import { getActivityDir, getUserAgentsDir } from '../state.js';
 import { normalizeHost } from '../machine-id.js';
 import { projectKeyFromCwd } from '../project-key.js';
 import { stampProvenance } from '../event-provenance.js';
-import { pythonToolRegistryLiteral, pythonValueFlagsLiteral, } from '../session/bash-command.js';
-/** The set of milestone events, for tier classification and ordering. */
+import { pythonToolRegistryLiteral, pythonValueFlagsLiteral, } from '@phnx-labs/sessions-cli/reader';
 export const MILESTONE_EVENTS = [
     'plan.created',
     'pr.opened',
@@ -46,11 +26,6 @@ export const MILESTONE_EVENTS = [
     'image.upscaled',
     'metadata.edited',
     'status.posted',
-    // NOTE: intentionally absent from the Python hook's own MILESTONE_EVENTS copy
-    // (see ACTIVITY_LOG_HOOK_SCRIPT below) — that set only classifies events the
-    // hook itself writes from PreToolUse/PostToolUse, and the hook never writes
-    // this one. activity.test.ts pins the difference so the divergence stays
-    // deliberate rather than becoming drift.
     'factory.launch',
     'status.blocked',
 ];
@@ -58,11 +33,6 @@ const MILESTONE_SET = new Set(MILESTONE_EVENTS);
 export function tierForEvent(event) {
     return MILESTONE_SET.has(event) ? 'milestone' : 'activity';
 }
-/**
- * Coerce an unknown value into a clean {@link Attachment}[] — a fail-open reader
- * over user/agent-written JSON. Drops entries without a usable `href`, clamps
- * `kind` to a string, and keeps only primitive `meta` values.
- */
 export function sanitizeAttachments(value) {
     if (!Array.isArray(value))
         return undefined;
@@ -103,11 +73,6 @@ function activityPath(root, sessionId) {
         throw new Error(`Invalid activity session id: ${sessionId}`);
     return path.join(root, `${safe}.jsonl`);
 }
-/**
- * Append one event to a session's activity log. Primarily the Python hook
- * writes these at runtime; this TS writer exists for tests and any in-process
- * emitter. Uses O_APPEND so concurrent appends never interleave a line.
- */
 export function appendActivityEvent(event, root) {
     const dir = root ?? getActivityDir();
     fs.mkdirSync(dir, { recursive: true });
@@ -119,10 +84,6 @@ export function appendActivityEvent(event, root) {
     };
     fs.appendFileSync(activityPath(dir, event.sessionId), `${JSON.stringify(record)}\n`, { mode: 0o644 });
 }
-/**
- * Parse one activity log line. Tolerant by design: a blank, corrupt, or
- * half-written line is skipped rather than failing the whole read.
- */
 export function parseActivityLine(line) {
     const trimmed = line.trim();
     if (!trimmed)
@@ -161,12 +122,10 @@ export function parseActivityLine(line) {
         };
     }
     catch {
-        return undefined; // skip corrupt / partial lines (fail-open reader)
+        return undefined;
     }
 }
-/** Per-session byte budget for a bounded tail read of an activity log. */
 export const ACTIVITY_TAIL_BYTES = 256 * 1024;
-/** Read the tail of a file as UTF-8, bounded to the last `maxBytes`. */
 function readTail(file, maxBytes) {
     let fd;
     try {
@@ -179,7 +138,6 @@ function readTail(file, maxBytes) {
         const buf = Buffer.allocUnsafe(len);
         fs.readSync(fd, buf, 0, len, start);
         let text = buf.toString('utf-8');
-        // Drop a leading partial line when we started mid-file.
         if (start > 0) {
             const nl = text.indexOf('\n');
             text = nl >= 0 ? text.slice(nl + 1) : '';
@@ -194,17 +152,11 @@ function readTail(file, maxBytes) {
             fs.closeSync(fd);
     }
 }
-// Process-local tail cache: bounded independently of the number of historical
-// sessions or directories a long-lived consumer visits. Never expose cached
-// objects: callers enrich and mutate returned events (including nested values).
 const ACTIVITY_CACHE_BYTES = 32 * 1024 * 1024;
 const activityTails = new Map();
-// A separate LRU of payload references lets pressure release parsed events
-// without repeatedly walking thousands of summaries that cannot shrink.
 const activityTailPayloads = new Map();
 let activityTailBytes = 0;
 let activityTailReads = 0;
-/** Read-only process-local diagnostics; no event content or file paths. */
 export function getActivityCacheStats() {
     return {
         entries: activityTails.size,
@@ -226,8 +178,6 @@ function activitySummaryWeight(key, stamp) {
 }
 function retainActivityTail(key, result, sinceMs) {
     const summaryWeight = activitySummaryWeight(key, result.stamp);
-    // Even metadata is byte-bounded. A tail whose summary cannot fit still
-    // returns normally, but must not evict the cache or be retained over budget.
     if (summaryWeight > ACTIVITY_CACHE_BYTES)
         return;
     const retained = { ...result };
@@ -235,8 +185,6 @@ function retainActivityTail(key, result, sinceMs) {
         retained.events = undefined;
         retained.weight = summaryWeight;
     }
-    // Prefer compact history over payloads, retaining all summaries that fit
-    // instead of imposing a file-count cap that thrashes on each directory scan.
     for (const [oldKey, old] of activityTailPayloads) {
         if (activityTailBytes + retained.weight <= ACTIVITY_CACHE_BYTES)
             break;
@@ -246,8 +194,6 @@ function retainActivityTail(key, result, sinceMs) {
         old.weight = weight;
         activityTailPayloads.delete(oldKey);
     }
-    // If all existing entries are summaries, sacrifice the incoming payload
-    // before evicting history. The current caller still receives result.events.
     if (activityTailBytes + retained.weight > ACTIVITY_CACHE_BYTES) {
         retained.events = undefined;
         retained.weight = summaryWeight;
@@ -261,9 +207,6 @@ function retainActivityTail(key, result, sinceMs) {
     activityTailBytes += retained.weight;
 }
 function activityStamp(file) {
-    // ctime catches same-size rewrites even when a producer restores mtime;
-    // device/inode catches atomic replacement. Nanoseconds avoid rounding away
-    // changes made between consecutive polls on high-resolution filesystems.
     const st = fs.statSync(file, { bigint: true });
     return `${st.dev}:${st.ino}:${st.size}:${st.mtimeNs}:${st.ctimeNs}`;
 }
@@ -290,7 +233,6 @@ function readActivityTail(file, maxBytes, sinceMs = -Infinity) {
     forgetActivityTail(key);
     activityTailReads++;
     const text = readTail(file, maxBytes);
-    // Transient I/O failure is not an empty file snapshot; retry next read.
     if (text === undefined)
         return { stamp, events: [], newestMs: -Infinity, weight: 0 };
     const events = [];
@@ -306,31 +248,23 @@ function readActivityTail(file, maxBytes, sinceMs = -Infinity) {
                 newestMs = Math.max(newestMs, ms);
         }
         catch {
-            // The tolerant parser historically accepts truthy non-string values.
-            // Do not introduce a conversion error before the caller's event filters
-            // (or into session reads, which never converted timestamps at all).
             newestMs = Infinity;
         }
     }
-    // Bound retained source-derived strings, objects, and entry overhead. Large
-    // one-off tails still read normally, but cannot displace the entire cache.
     const weight = text.length * 2 + events.length * 1024 + activitySummaryWeight(key, stamp);
     const result = { stamp, events, newestMs, weight };
     try {
-        // A writer racing the read must not pin a mixed snapshot as unchanged.
         if (activityStamp(file) === stamp) {
             retainActivityTail(key, result, sinceMs);
         }
     }
-    catch { /* Deleted during the read: return this snapshot without caching. */ }
+    catch { }
     return result;
 }
-/** Read all events for one session (bounded tail). */
 export function readSessionActivity(sessionId, root, maxBytes = ACTIVITY_TAIL_BYTES) {
     const dir = root ?? getActivityDir();
     return structuredClone(readActivityTail(activityPath(dir, sessionId), maxBytes).events ?? []);
 }
-/** List session ids that have an activity log. */
 function listActivitySessions(root) {
     const dir = root ?? getActivityDir();
     try {
@@ -340,10 +274,6 @@ function listActivitySessions(root) {
         return [];
     }
 }
-/**
- * Merge recent events across every session's log, newest first. Reads only the
- * tail of each file, so cost scales with active sessions, not transcript size.
- */
 export function readRecentActivity(opts = {}) {
     const dir = opts.root ?? getActivityDir();
     const sinceMs = opts.sinceMs ?? 0;
@@ -366,11 +296,6 @@ export function readRecentActivity(opts = {}) {
     all.sort((a, b) => Date.parse(b.ts) - Date.parse(a.ts));
     return structuredClone(typeof opts.limit === 'number' ? all.slice(0, opts.limit) : all);
 }
-/**
- * Split a chronological event list into individual milestones plus a
- * count map for the routine (tier-2) events, so a reader shows recognizable
- * deliverables in full and collapses the noise.
- */
 export function collapseActivity(events) {
     const milestones = [];
     const counts = {};
@@ -387,14 +312,6 @@ export function collapseActivity(events) {
     }
     return { milestones, counts, subagentCount };
 }
-// ---------------------------------------------------------------------------
-// Bridge into the unified event stream (lib/event-stream.ts)
-// ---------------------------------------------------------------------------
-/**
- * Normalize one activity event into the shared {@link EventRecord} shape so the
- * agent-semantic stream reads through the same reader as operational events.
- * `module` is stamped `activity` so `--module` filters partition the two cleanly.
- */
 function activityEventToRecord(ev) {
     return {
         ts: ev.ts,
@@ -411,7 +328,6 @@ function activityEventToRecord(ev) {
         session: ev.sessionId,
         osUser: 'unknown',
         transport: 'local',
-        // payload
         agent: ev.agent,
         actor: ev.actor ?? 'unknown',
         kind: ev.kind ?? 'unknown',
@@ -430,14 +346,9 @@ function activityEventToRecord(ev) {
         ...(ev.attachments?.length ? { attachments: ev.attachments } : {}),
     };
 }
-/** Read recent activity across sessions as unified {@link EventRecord}s. */
 export function readActivityAsEventRecords(opts = {}) {
     return readRecentActivity(opts).map(activityEventToRecord);
 }
-// ---------------------------------------------------------------------------
-// Rendering (shared by the feed activity lane and `agents feed --filter updates`)
-// ---------------------------------------------------------------------------
-/** Glyph + color + human label per event, so the lane reads at a glance. */
 const EVENT_STYLE = {
     'plan.created': { glyph: '◆', color: chalk.cyan, label: 'plan created' },
     'pr.opened': { glyph: '⇡', color: chalk.green, label: 'PR opened' },
@@ -458,12 +369,10 @@ const EVENT_STYLE = {
 function styleForEvent(event) {
     return EVENT_STYLE[event] ?? { glyph: '•', color: chalk.white, label: event };
 }
-/** One rendered activity line: `  <rel>  [host] <glyph label> detail url`. */
 export function formatActivityLine(ev, opts = {}) {
     const s = styleForEvent(ev.event);
     const host = opts.showHost && ev.host && ev.host !== 'unknown' ? chalk.gray(`[${ev.host}] `) : '';
     const label = s.color(`${s.glyph} ${s.label}`);
-    // Status posts are the message; allow a longer snippet than tool-derived detail.
     const detailLimit = ev.event === 'status.posted' ? 100 : 60;
     const detail = ev.detail ? ` ${truncate(ev.detail, detailLimit)}` : '';
     const url = ev.url ? chalk.gray(` ${ev.url}`) : '';
@@ -471,13 +380,6 @@ export function formatActivityLine(ev, opts = {}) {
     const when = chalk.gray(relTime(ev.ts).padStart(7));
     return `  ${when}  ${host}${label}${detail}${agent}${url}`;
 }
-// ---------------------------------------------------------------------------
-// Rich progress render (RUSH-2014): `status.posted` posts are the deliberate,
-// operator-facing announcements — a single truncated line under-serves them.
-// `formatProgressUpdate` renders each as a multi-line row with full identity
-// chips (agent · session · host · project) and any attached artifacts.
-// ---------------------------------------------------------------------------
-/** Glyph per attachment kind, so an artifact row reads at a glance. */
 const ATTACHMENT_GLYPH = {
     image: '🖼',
     audio: '♪',
@@ -488,7 +390,6 @@ const ATTACHMENT_GLYPH = {
 function attachmentGlyph(kind) {
     return ATTACHMENT_GLYPH[kind] ?? '📎';
 }
-/** Display name for an attachment: its `name`, else the basename of its href. */
 export function attachmentName(att) {
     if (att.name && att.name.trim())
         return att.name.trim();
@@ -497,29 +398,10 @@ export function attachmentName(att) {
     const base = slash >= 0 ? href.slice(slash + 1) : href;
     return base || href;
 }
-/**
- * Short session id for a chip: strip a known prefix (`session_`, `ses_`) then
- * take the first 8 chars — enough to disambiguate, matching `ag sessions`.
- */
 export function shortSessionId(sessionId) {
     const stripped = sessionId.replace(/^(session_|ses_)/, '');
     return stripped.slice(0, 8) || sessionId.slice(0, 8);
 }
-/**
- * Render a deliberate progress update (`status.posted`) as an operator-facing,
- * multi-line row with full identity — not a 60-char one-liner. Shape:
- *
- * ```
- *   ▸ update · 3m ago
- *     grok · 0108441e · yosemite-s1 · agents
- *     "CHANGELOG pushed; watching CI"
- *     ♪ draft.wav   🖼 cover.png
- *     ↳ ag focus 0108441e · ag sessions 0108441e
- * ```
- *
- * Chips (agent, short session id, host, project, optional joined ticket/label)
- * are shown only when known. Non-progress milestones keep {@link formatActivityLine}.
- */
 export function formatProgressUpdate(ev, opts = {}) {
     const shortId = shortSessionId(ev.sessionId);
     const lines = [];
@@ -547,31 +429,9 @@ export function formatProgressUpdate(ev, opts = {}) {
     lines.push(`    ${chalk.dim(`↳ ag focus ${shortId} · ag sessions ${shortId}`)}`);
     return lines.join('\n');
 }
-/**
- * Resolve a stable project/repo name from a working directory — the same fold
- * the `agents sessions` overview groups by ({@link projectKeyFromCwd}), so a
- * project reads identically in both views.
- */
 export function projectFromCwd(cwd) {
     return projectKeyFromCwd(cwd);
 }
-/**
- * Join session facts (ticket / project / execution host) onto each event by
- * `sessionId`. A hint wins; otherwise a CANONICAL def match (`canonicalProject`)
- * upgrades whatever the event carries; otherwise pre-baked enriched fields (from
- * a remote peer that already enriched its own stream) are preserved, and
- * project/host fall back to what the event itself carries (`cwd`, `host`).
- *
- * The def match ranks above the pre-baked stamp because the stamp may be stale
- * (posted before the def existed) or skewed (a peer whose defs haven't synced);
- * the match is pure prefix compare against local defs, so a different-home
- * peer's path simply doesn't match and its stamp is honored as before.
- *
- * `resolveProject` is how a caller reading its OWN machine's logs upgrades the
- * cwd fold to real repository detection ({@link resolveProjectKey}); it defaults
- * to the pure {@link projectFromCwd}, which is all a path from another machine
- * can be resolved with. Pure given pure resolvers.
- */
 export function enrichActivityEvents(events, hints, resolveProject = projectFromCwd, canonicalProject) {
     const bySession = new Map();
     for (const h of hints)
@@ -591,13 +451,6 @@ export function enrichActivityEvents(events, hints, resolveProject = projectFrom
         };
     });
 }
-/**
- * Validate + host-tag one peer's `activity --json` payload for the fan-out
- * merge. Mirrors {@link parseLine}: skip anything missing `event`/`sessionId`/
- * `ts`, drop corrupt items. The event's own `host` is the execution host and is
- * authoritative; only fall back to the dialed peer's `machine` when it's absent.
- * Enriched fields the peer stamped (project/ticket/executionHost) ride through.
- */
 export function parseActivityPayload(stdout, machine) {
     let parsed;
     try {
@@ -620,12 +473,6 @@ export function parseActivityPayload(stdout, machine) {
     }
     return out;
 }
-/**
- * Merge local + remote event lists, keeping the first copy of a given
- * host/session/ts/event and sorting newest first. Cross-machine activity dirs
- * can sync in a peer's own events, so the identity key dedupes those (mirrors
- * `mergeFeedBlocks`).
- */
 export function mergeActivityEvents(...groups) {
     const byKey = new Map();
     for (const ev of groups.flat()) {
@@ -635,19 +482,6 @@ export function mergeActivityEvents(...groups) {
     }
     return [...byKey.values()].sort((a, b) => Date.parse(b.ts) - Date.parse(a.ts));
 }
-/**
- * Apply `--limit` to the events a reader will actually SHOW.
- *
- * The default view collapses routine work (`file.edited`) to a count and shows
- * milestones individually, so a plain `slice(limit)` spends the whole budget on
- * churn: one busy machine editing 40 files hid every other device's PRs behind
- * a single `file edited ×40` line. Milestones therefore carry the cap, and the
- * routine events that ride along are the ones newer than the last milestone
- * kept — so the collapsed counts describe exactly the window on screen.
- *
- * With `all` (routine shown inline) every event is displayed, so the cap is the
- * plain slice again. Input must be newest-first; output preserves that order.
- */
 export function capActivityEvents(events, limit, opts = {}) {
     if (!Number.isFinite(limit) || limit <= 0)
         return [];
@@ -659,8 +493,6 @@ export function capActivityEvents(events, limit, opts = {}) {
     for (const ev of events) {
         if (tierForEvent(ev.event) === 'milestone') {
             if (milestones >= limit) {
-                // The cap is reached: the window ends at the oldest milestone kept, so
-                // trailing routine events (older than it) are outside it.
                 return out.slice(0, lastMilestoneIdx + 1);
             }
             milestones += 1;
@@ -670,7 +502,6 @@ export function capActivityEvents(events, limit, opts = {}) {
     }
     return out;
 }
-/** The (key, label) an event sorts under for a given grouping dimension. */
 export function activityGroupKey(ev, by) {
     if (by === 'project') {
         const p = ev.project ?? projectFromCwd(ev.cwd);
@@ -683,11 +514,6 @@ export function activityGroupKey(ev, by) {
     const a = ev.agent;
     return a ? { key: a, label: a } : { key: '', label: 'unknown agent' };
 }
-/**
- * Bucket events by project, device, or agent. Groups are ordered by event count
- * (desc) then label; the "unknown" bucket always sorts last. Input order is
- * preserved within a group, so newest-first survives when the input is sorted.
- */
 export function groupActivity(events, by) {
     const byKey = new Map();
     for (const ev of events) {
@@ -708,11 +534,6 @@ export function groupActivity(events, by) {
         return a.label.localeCompare(b.label);
     });
 }
-/**
- * Narrow events to those whose project, device/host, agent, event kind, or
- * ticket contains `filter` (case-insensitive substring). An empty filter is a
- * no-op. Pure.
- */
 export function filterActivityEvents(events, filter) {
     const needle = filter.trim().toLowerCase();
     if (!needle)
@@ -722,19 +543,12 @@ export function filterActivityEvents(events, filter) {
         return fields.some((f) => typeof f === 'string' && f.toLowerCase().includes(needle));
     });
 }
-/**
- * Narrow events to one resolved project, exact match on the enriched label
- * (unlike {@link filterActivityEvents}'s cross-field substring). This is the
- * `--project` flag: the label is canonical (a defined project's name) once the
- * reader's resolver has run, so a multi-repo project matches as one bucket. Pure.
- */
 export function filterActivityByProject(events, project) {
     const name = project.trim();
     if (!name)
         return events;
     return events.filter((ev) => ev.project === name);
 }
-/** One rendered enriched line: the base activity line + `· project · ticket` tags. */
 export function formatEnrichedActivityLine(ev, opts = {}) {
     const base = formatActivityLine(ev, { showHost: opts.showHost });
     const tags = [];
@@ -745,14 +559,7 @@ export function formatEnrichedActivityLine(ev, opts = {}) {
     const suffix = tags.length > 0 ? chalk.gray(`  · ${tags.join(' · ')}`) : '';
     return `${opts.indent ?? ''}${base}${suffix}`;
 }
-/** Max device names named in a group header before the rest collapse to `+N`. */
 const GROUP_HEADER_DEVICE_LIMIT = 3;
-/**
- * The distinct machines a group's events ran on, most-active first then
- * alphabetical — so a project header can say WHERE the work happened without
- * sub-grouping the timeline. Prefers the session-joined `executionHost` (where
- * the process really lives) over the raw emitting `host`. Pure.
- */
 export function activityGroupDevices(events) {
     const counts = new Map();
     for (const ev of events) {
@@ -765,14 +572,6 @@ export function activityGroupDevices(events) {
         .sort((a, b) => (b[1] !== a[1] ? b[1] - a[1] : a[0].localeCompare(b[0])))
         .map(([host]) => host);
 }
-/**
- * The trailing facts for one grouped bucket: `N events · M milestones`, plus
- * the machines the work ran on when `showDevices` is set (redundant when the
- * grouping dimension IS the device, so the caller decides). The device list is
- * capped at {@link GROUP_HEADER_DEVICE_LIMIT} with a `+N` tail, so a project
- * touched by a dozen boxes stays one scannable line. Separate from the label so
- * a renderer can color the two differently without re-splitting a string.
- */
 export function formatActivityGroupMeta(group, opts = {}) {
     const { milestones } = collapseActivity(group.events);
     const n = group.events.length;
@@ -790,19 +589,6 @@ export function formatActivityGroupMeta(group, opts = {}) {
     }
     return parts.join(' · ');
 }
-// ---------------------------------------------------------------------------
-// Hook installation
-// ---------------------------------------------------------------------------
-/**
- * The activity-log hook (Python), sibling to 10-feed-publish.py. Classifies
- * PreToolUse/PostToolUse payloads into activity events and appends one JSONL
- * line per event to ~/.agents/.history/activity/<sessionId>.jsonl.
- *
- * Matcher-gated to mutating/milestone tools (Bash|Task|ExitPlanMode|Write|
- * Edit|MultiEdit|TodoWrite|update_plan|TaskUpdate|todo_write|TaskCreate) so
- * read-only tools never pay the hook cost. Fail-open: any error is swallowed so
- * a logging hiccup never blocks a tool call.
- */
 export const ACTIVITY_LOG_HOOK_SCRIPT = String.raw `#!/usr/bin/env python3
 """Append agent-activity events for 'agents feed'.
 
@@ -824,7 +610,7 @@ import shlex
 import socket
 from datetime import datetime, timezone
 
-MAX_LOG_BYTES = 5 * 1024 * 1024  # cap a pathological session's log
+MAX_LOG_BYTES = 5 * 1024 * 1024
 MILESTONE_EVENTS = {
     "plan.created", "pr.opened", "pr.merged", "worktree.created",
     "worktree.removed", "commit.created", "pushed", "subagent.spawned",
@@ -833,15 +619,12 @@ MILESTONE_EVENTS = {
     "status.posted",
 }
 
-# Deliverable file types + locations -- a Write here is a recognizable artifact
-# (an HTML plan, a PDF report, a rendered image), not a routine code edit.
 ARTIFACT_EXTS = {
     ".html", ".htm", ".pdf", ".png", ".jpg", ".jpeg", ".gif", ".svg",
     ".webp", ".mp4", ".mov", ".webm", ".csv", ".xlsx", ".pptx", ".docx",
 }
 ARTIFACT_DIR_HINTS = ("/tmp/", "/downloads/", "/.agents/artifacts/")
 
-# Checklist tools across harnesses. The value is the key that holds the item list.
 CHECKLIST_TOOLS = {
     "TodoWrite": "todos",
     "todo_write": "todos",
@@ -865,17 +648,10 @@ def first_line(text, limit=140):
     return ""
 
 
-# Canonical command taxonomy for Bash tool calls, generated from the single
-# source of truth in lib/session/bash-command.ts's TOOL_REGISTRY (#1889) so the
-# two can no longer drift — this hook runs standalone under python3 and can't
-# import that module, so the literal below is generated, not hand-duplicated.
 BASH_TOOL_REGISTRY = {
 ${pythonToolRegistryLiteral()}
 }
 
-# Two-level tools mapped to the flags that consume the following token as their
-# value, per tool; the subcommand scan skips both. Generated from VALUE_FLAGS in
-# lib/session/bash-command.ts (#1889) — TWO_LEVEL_TOOLS is derived from its keys.
 VALUE_FLAGS = {
 ${pythonValueFlagsLiteral()}
 }
@@ -893,11 +669,9 @@ def _unwrap_command(cmd):
     ssh = re.match(r'^ssh\s+\S+\s+["\']?(.+?)["\']?\s*(?:\|.*)?$', s)
     if ssh:
         return _unwrap_command(ssh.group(1))
-    # VAR=value prefix (value may be a single- or double-quoted string with spaces)
     env = re.match(r'^([A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|' + r"'[^']*'" + r'|\S+)\s+)+(.+)$', s)
     if env:
         return _unwrap_command(env.group(2))
-    # export VAR=value && command / export A=1 B=2; command
     export_prefix = re.match(
         r'^export\s+(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|' + r"'[^']*'" + r'|\S+)\s+)*'
         r'[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|' + r"'[^']*'" + r'|\S+)\s*(?:&&|;|\n)\s*([\s\S]+)$',
@@ -905,15 +679,12 @@ def _unwrap_command(cmd):
     )
     if export_prefix:
         return _unwrap_command(export_prefix.group(1))
-    # sudo / time prefix (value-taking flags such as -u user consume their argument)
     prefix = re.match(r'^(?:sudo|time)(?:\s+(?:-[uUgGhpCrtDR]\s+\S+|-\S+))*\s+(.+)$', s)
     if prefix:
         return _unwrap_command(prefix.group(1))
-    # set -euo pipefail && command / set -x; command
     set_prefix = re.match(r'^set\s+[^&;\n]+?(?:&&|;|\n)\s*([\s\S]+)$', s)
     if set_prefix:
         return _unwrap_command(set_prefix.group(1))
-    # cd foo && command  (also ; and newline separators)
     cd = re.match(r'^cd\s+\S+\s*(?:&&|;|\n)\s*([\s\S]+)$', s)
     if cd:
         return _unwrap_command(cd.group(1))
@@ -1033,8 +804,6 @@ def classify_bash_command(command):
         base = base[:-4]
     info = BASH_TOOL_REGISTRY.get(base)
     if not info:
-        # Known two-level tool absent from the registry (docker/kubectl/rush/
-        # openclaw) still surfaces its subcommand; category stays 'other'.
         sub = _scan_subcommand(tokens, base) if base in TWO_LEVEL_TOOLS else ""
         summary = "{} {}".format(base, sub) if sub else first
         return {"tool": first, "category": "other", "subcommand": sub, "action": "running command", "summary": summary}
@@ -1164,7 +933,7 @@ def _read_transcript_checklists(transcript_path, current_tool, current_items):
         with open(transcript_path, "r", encoding="utf-8", errors="ignore") as f:
             f.seek(start)
             if start > 0:
-                f.readline()  # drop a leading partial line
+                f.readline()
             lines = f.readlines()
     except Exception:
         return None
@@ -1207,8 +976,6 @@ def _read_transcript_checklists(transcript_path, current_tool, current_items):
             if not items:
                 continue
             ids = {str(item.get("id")) for item in items if item.get("id")}
-            # Skip the most recent matching checklist entry once; that is the
-            # current call already reflected in the transcript.
             if not skipped_current and name == current_tool and ids == current_ids:
                 skipped_current = True
                 continue
@@ -1275,7 +1042,7 @@ def _claude_task_state(transcript_path, exclude_task_id=None):
     except Exception:
         return state
 
-    updates = []  # (task_id, status, line_index)
+    updates = []
     for idx, line in enumerate(lines):
         line = line.strip()
         if not line:
@@ -1317,7 +1084,6 @@ def _claude_task_state(transcript_path, exclude_task_id=None):
                     ""
                 )
                 if subject:
-                    # Link subject to the tool_use id so the result can map it.
                     tool_id = tu.get("id")
                     if tool_id:
                         state.setdefault("__pending_subject", {})[tool_id] = subject
@@ -1334,7 +1100,6 @@ def _claude_task_state(transcript_path, exclude_task_id=None):
                     state[task_id]["subject"] = task["subject"]
                 if task.get("status"):
                     state[task_id]["status"] = str(task.get("status")).lower()
-                # Link any pending subject from the matching tool_use id.
                 tool_use_id = record.get("tool_use_id") or ""
                 pending = state.get("__pending_subject", {})
                 if tool_use_id and tool_use_id in pending:
@@ -1352,7 +1117,6 @@ def _claude_task_state(transcript_path, exclude_task_id=None):
             if updates[i][0] == exclude_task_id:
                 del updates[i]
                 break
-        # Rebuild statuses from remaining updates.
         for task_id in list(state.keys()):
             if task_id.startswith("__"):
                 continue
@@ -1364,15 +1128,12 @@ def _claude_task_state(transcript_path, exclude_task_id=None):
             if task_id in state:
                 state[task_id]["status"] = status
 
-    # Drop tasks removed from the checklist (deleted/cancelled): they are gone
-    # from the user-visible list, so they must not count toward the N/M total.
     for task_id in list(state.keys()):
         if task_id.startswith("__"):
             continue
         if state[task_id].get("status") in ("deleted", "cancelled", "canceled", "removed"):
             del state[task_id]
 
-    # Drop internal bookkeeping.
     state.pop("__pending_subject", None)
     return state
 
@@ -1391,7 +1152,6 @@ def _checklist_events(payload, hook_event):
             tool_input.get("title") or
             "task"
         )
-        # Only announce the checklist on the very first task creation.
         current_tool_use_id = payload.get("tool_use_id", "")
         transcript_path = payload.get("transcript_path")
         if _has_previous_task_create(transcript_path, current_tool_use_id):
@@ -1406,9 +1166,6 @@ def _checklist_events(payload, hook_event):
     if not items:
         return []
 
-    # Full-list tools (TodoWrite, update_plan) send the whole checklist every
-    # time. Per-task update tools (TaskUpdate) send only the changed item, so
-    # totals and subject must be resolved from the previous full-list state.
     list_key = {"todos": "todos", "tasks": "tasks", "plan": "plan"}.get(kind)
     is_full_list = list_key is not None and list_key in tool_input
 
@@ -1442,8 +1199,6 @@ def _checklist_events(payload, hook_event):
             events.append(("task.completed", f"{subject} {done_count}/{total} done"))
         return events
 
-    # For TaskUpdate without a previous full-list state, fold the Claude
-    # TaskCreate/TaskUpdate history to resolve subject and N/M.
     if tool_name == "TaskUpdate" and previous is None:
         task_id = str(items[0].get("id")) if items else ""
         task_state = _claude_task_state(
@@ -1465,7 +1220,6 @@ def _checklist_events(payload, hook_event):
     completed = [i for i in items if i.get("status") == "completed"]
 
     if previous is None:
-        # First checklist call in this session.
         events = []
         events.append(("checklist.created", f"{total} task{'s' if total != 1 else ''}"))
         for item in completed:
@@ -1515,7 +1269,6 @@ def build_event(payload, hook_event):
     tool_input = payload.get("tool_input", {}) or {}
     tool_response = payload.get("tool_response", {})
 
-    # Checklist completions first -- cheap guard above already filtered tool name.
     checklist = _checklist_events(payload, hook_event)
     if checklist:
         return [_make_record(event, detail, tool_name) for event, detail in checklist], tool_name
@@ -1538,7 +1291,6 @@ def build_event(payload, hook_event):
             cmd = tool_input.get("command", "")
             info = classify_bash_command(cmd)
             records = []
-            # Always emit a structured bash.executed activity event.
             bash_record = _make_record("bash.executed", info.get("summary") or first_line_of_command(cmd), tool_name)
             bash_record["category"] = info.get("category")
             bash_record["bashTool"] = info.get("tool")
@@ -1555,8 +1307,6 @@ def build_event(payload, hook_event):
             return records, tool_name
         elif tool_name in ("Write", "Edit", "MultiEdit"):
             fp = tool_input.get("file_path") or tool_input.get("path") or ""
-            # A freshly-written deliverable is a milestone; edits and code
-            # writes stay routine and collapse to a count.
             if tool_name == "Write" and is_artifact(fp):
                 event = "artifact.created"
             else:
@@ -1579,7 +1329,6 @@ def main():
     except Exception:
         return
 
-    # Sub-agent gate -- only the top-level agent logs.
     if payload.get("agent_type"):
         return
 
@@ -1597,7 +1346,6 @@ def main():
     activity_dir = os.path.join(home, ".agents", ".history", "activity")
     target = os.path.join(activity_dir, safe_session + ".jsonl")
 
-    # Identity (mirrors 10-feed-publish.py).
     mailbox_id = os.path.basename(
         os.environ.get("AGENTS_MAILBOX_DIR", "").rstrip("/")
     ) or session_id
@@ -1626,7 +1374,6 @@ def main():
 
     try:
         os.makedirs(activity_dir, exist_ok=True)
-        # Cap growth: once over the size limit, keep only milestones.
         try:
             over_limit = os.path.getsize(target) > MAX_LOG_BYTES
         except OSError:
@@ -1637,16 +1384,15 @@ def main():
                     continue
                 f.write(json.dumps(record) + "\n")
     except Exception:
-        pass  # fail open
+        pass
 
 
 if __name__ == "__main__":
     try:
         main()
     except Exception:
-        pass  # fail open
+        pass
 `;
-/** Hook manifest entries (agents.yaml shape) for the activity-log hook. */
 const ACTIVITY_HOOK_DEFINITIONS = {
     'activity-log-intent': {
         agents: ['claude'],
@@ -1663,11 +1409,6 @@ const ACTIVITY_HOOK_DEFINITIONS = {
         timeout: 5,
     },
 };
-/**
- * Install the activity-log hook script into the user hooks dir and add its
- * manifest entries to the user agents.yaml. Mirrors {@link ensureFeedPublishHook}
- * in feed.ts -- idempotent, and never writes the read-only system repo.
- */
 export function ensureActivityLogHook(userAgentsDir = getUserAgentsDir()) {
     try {
         const hooksDir = path.join(userAgentsDir, 'hooks');
@@ -1695,12 +1436,6 @@ export function ensureActivityLogHook(userAgentsDir = getUserAgentsDir()) {
         }
         if (installed) {
             const tmpYaml = `${agentsYamlPath}.${process.pid}.tmp`;
-            // `flowCollectionPadding: false` matches the committed formatting — see the
-            // twin `ensureFeedPublishHook` in feed.ts. Without it, re-emitting a
-            // committed flow node (`[a, b]` -> `[ a, b ]`) leaves the git-backed
-            // `~/.agents` tree permanently dirty and blocks `agents repo pull`
-            // fleet-wide (RUSH-2505). This writer runs back-to-back with the feed one
-            // on the `agents feed` path, so both must round-trip cleanly.
             fs.writeFileSync(tmpYaml, stringifyDoc(yamlDoc));
             fs.renameSync(tmpYaml, agentsYamlPath);
         }