@phnx-labs/agents-cli 1.20.72 → 1.20.74

package/dist/index.js

@@ -26,6 +26,11 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = path.join(__dirname, '..', 'package.json');
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
 const VERSION = packageJson.version;
+if (process.argv[2] === '__vault-age-helper') {
+    const { runVaultAgeHelperCli } = await import('./lib/secrets/vault-age-helper.js');
+    await runVaultAgeHelperCli();
+    process.exit(process.exitCode ?? 0);
+}
 import { NPM_PACKAGE_NAME, deriveGlobalPrefix, detectPackageManager, installPackageIntoPrefix, installPackageWithBun, verifyInstalledVersion, refreshAliasShims, downloadVerifiedTarball, } from './lib/self-update.js';
 // Detect dev/working-tree builds and default the noisy startup steps off.
 // Three cases trip this:
@@ -50,7 +55,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadResources, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadCheck, loadStatus, loadProfiles, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadHq, loadFeed, loadActivity, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { emit, redactArgs } from './lib/events.js';
@@ -68,9 +73,18 @@ if (process.argv[2] === '__shim') {
     const code = await execShimPassthrough(agent, rawArgs, process.cwd(), pinned || undefined);
     process.exit(code);
 }
+if (process.argv[2] === '__daemon-run') {
+    const { runDaemon } = await import('./lib/daemon.js');
+    await runDaemon();
+    process.exit(process.exitCode ?? 0);
+}
+// White-label: the shim for a brand (e.g. `jack`) exports AGENTS_BRAND, so the
+// CLI presents its own name/help/errors as the brand. Unbranded (AGENTS_BRAND
+// unset) resolves to 'agents' and everything below is byte-identical to before.
+const BRAND = resolveBrandName();
 const program = new Command();
 program
-    .name('agents')
+    .name(BRAND)
     .description('Environment manager for AI agents')
     .version(VERSION)
     .option('--verbose', 'Show startup self-heal details on stderr')
@@ -86,7 +100,7 @@ program
 function auditCommandPath(cmd) {
     const parts = [];
     let c = cmd;
-    while (c && c.name() && c.name() !== 'agents') {
+    while (c && c.name() && c.name() !== BRAND) {
         parts.unshift(c.name());
         c = c.parent;
     }
@@ -129,11 +143,36 @@ program.hook('postAction', (_thisCommand, actionCommand) => {
         // Best-effort completion record; the start line is the durable audit fact.
     }
 });
+/**
+ * Skin the static root help for a brand: rewrite the visible `agents` command
+ * examples to the brand name and drop lines for commands this brand disabled.
+ * A no-op for the unbranded `agents` CLI with nothing disabled.
+ */
+function brandRootHelp(raw) {
+    let text = raw;
+    if (BRAND !== 'agents') {
+        text = text
+            .replace(/Usage: agents /g, `Usage: ${BRAND} `)
+            .replace(/^ {2}agents /gm, `  ${BRAND} `)
+            .replace(/Run 'agents /g, `Run '${BRAND} `);
+    }
+    const disabled = disabledCommandsForActiveBrand();
+    if (disabled.size > 0) {
+        text = text
+            .split('\n')
+            .filter((line) => {
+            const m = line.match(/^ {2}([a-z][\w-]*)/);
+            return !(m && disabled.has(m[1]));
+        })
+            .join('\n');
+    }
+    return text;
+}
 // Custom help for the main program only
 const originalHelpInformation = program.helpInformation.bind(program);
 program.helpInformation = function () {
-    if (this.name() === 'agents' && !this.parent) {
-        return `Usage: agents [command] [options]
+    if (this.name() === BRAND && !this.parent) {
+        return brandRootHelp(`Usage: agents [command] [options]
 
 Install, configure, run, and dispatch AI coding agents from one place.
 Works with Claude, Codex, Gemini, Cursor, OpenCode, OpenClaw, and Droid.
@@ -154,6 +193,7 @@ Agent versions:
   trash                           Inspect and restore soft-deleted version directories
   view [agent[@version]]          List versions, or inspect one in detail
   inspect <target>                Deep details for one agent+version, or a DotAgents repo (user|system|project|alias|path)
+  resources                       Show merged DotAgents resources with their winning layer
 
 Agent configuration (synced across versions):
   rules                           Instructions given to agents (CLAUDE.md, etc.)
@@ -173,6 +213,7 @@ Run and dispatch:
   run <agent|profile> [prompt]    Run an agent. Omit prompt for interactive mode.
   defaults                        Configure run defaults by agent/version selector
   teams                           Coordinate multiple agents on shared work
+  hq                              JSON bridge for the interactive Agents HQ floor
   routines                        Run agents on a cron schedule (scheduler auto-starts)
   webhook                         Receive signed GitHub/Linear webhooks for trigger routines
   funnel                          Expose a webhook receiver through Tailscale Funnel
@@ -182,6 +223,7 @@ Run and dispatch:
   pty                             Drive interactive terminal programs (REPLs, TUIs) via a persistent PTY session
 
 Credentials and profiles:
+  profile                         Activate resource profiles across skills, MCP, permissions, and secrets
   profiles                        Bundles of (host CLI, endpoint, model, auth)
   secrets                         Keychain-backed env bundles; use 'secrets exec <bundle> -- <cmd>' to inject into a subprocess
 
@@ -213,7 +255,7 @@ Options:
   --verbose                       Show startup self-heal details on stderr
 
 System config lives in ~/.agents/.system/. Run 'agents <command> --help' for details.
-`;
+`);
     }
     return originalHelpInformation();
 };
@@ -251,6 +293,7 @@ async function showWhatsNew(fromVersion, toVersion) {
 }
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
 import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir, getRuntimeStateDir } from './lib/state.js';
+import { resolveBrandName, disabledCommandsForActiveBrand } from './lib/brand.js';
 import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, findAgentsCliInstalls, } from './lib/self-update.js';
 const UPDATE_CHECK_FILE = getUpdateCheckPath();
 /**
@@ -668,7 +711,9 @@ async function registerEagerForRequest(name) {
 async function registerAllEagerCommands() {
     await reg(loadView);
     await reg(loadShare);
+    await reg(loadSend);
     await reg(loadInspect);
+    await reg(loadResources);
     await reg(loadFeedback);
     await reg(loadCommands);
     await reg(loadHooks);
@@ -685,8 +730,8 @@ async function registerAllEagerCommands() {
     await reg(loadWorktree);
     await reg(loadVersions);
     await reg(loadImport);
+    await reg(loadExport);
     await reg(loadPackages);
-    await reg(loadDaemon);
     await reg(loadRoutines);
     await reg(loadMonitors);
     await reg(loadRun);
@@ -703,6 +748,7 @@ async function registerAllEagerCommands() {
     registerExecAliasCommand(program);
     await reg(loadProfiles);
     await reg(loadSecrets);
+    await reg(loadLogin);
     await reg(loadWallet);
     await reg(loadHelper);
     await reg(loadMenubar);
@@ -717,6 +763,7 @@ async function registerAllEagerCommands() {
     await reg(loadOutput);
     await reg(loadBudget);
     await reg(loadAlias);
+    await reg(loadMine);
     await reg(loadPty);
     await reg(loadTmux);
     await reg(loadWatchdog);
@@ -728,7 +775,9 @@ async function registerAllEagerCommands() {
     await reg(loadAudit);
     await reg(loadWebhook);
     await reg(loadFunnel);
+    await reg(loadHq);
     await reg(loadFeed);
+    await reg(loadActivity);
     await reg(loadMailboxes);
     await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
@@ -795,13 +844,19 @@ const verboseStartup = passedArgs.includes('--verbose');
 // Help and version output are pure documentation — they must never gate on
 // setup, otherwise `agents <cmd> --help` becomes useless on a fresh box.
 const helpOrVersionRequested = passedArgs.some((arg) => arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V');
+// White-label: a brand can hide built-in top-level commands. A hidden command
+// must behave as if it doesn't exist under this brand (unknown-command +
+// spellcheck), while `agents` itself is unaffected. `brandDisabled` is empty for
+// the unbranded CLI, so all of this is a no-op there.
+const brandDisabled = disabledCommandsForActiveBrand();
+const requestedIsDisabled = requestedCommand !== undefined && brandDisabled.has(requestedCommand);
 // `--host` passthrough: run this invocation on a remote machine over SSH instead
 // of locally. Handled before any local command registration / update check /
 // background sync — a remote run needs none of that. Only the allowlisted
 // read-only + config + teams commands route here; `run`/`sessions` are absent
 // from the table and fall through to their own richer `--host` handling below.
 // `--help`/`--version` stay local (docs must work without a reachable host).
-if (requestedCommand !== undefined && !helpOrVersionRequested) {
+if (requestedCommand !== undefined && !helpOrVersionRequested && !requestedIsDisabled) {
     const { maybeRunOnHost } = await import('./lib/hosts/passthrough.js');
     if (await maybeRunOnHost(requestedCommand, passedArgs)) {
         process.exit(process.exitCode ?? 0);
@@ -810,7 +865,13 @@ if (requestedCommand !== undefined && !helpOrVersionRequested) {
 // Register only the command(s) this invocation actually uses. Lazy commands
 // (sessions/teams/cloud) are handled after applyGlobalHelpConventions below.
 const isLazyRequest = requestedCommand !== undefined && LAZY_COMMAND_NAMES.has(requestedCommand);
-if (requestedCommand !== undefined && !isLazyRequest) {
+if (requestedIsDisabled) {
+    // The brand turned this command off: register the full tree so the "did you
+    // mean" picker still works, then strip the disabled commands below so the
+    // request resolves as unknown.
+    await registerAllEagerCommands();
+}
+else if (requestedCommand !== undefined && !isLazyRequest) {
     const known = await registerEagerForRequest(requestedCommand);
     if (!known) {
         // Unknown top-level command: register the full tree so the "did you mean"
@@ -828,10 +889,19 @@ if (requestedCommand !== undefined && !isLazyRequest) {
 applyGlobalHelpConventions(program);
 // Lazy commands pull in the SQLite-backed session/cloud stack; register them
 // only when explicitly requested, keeping lightweight commands off that path.
-if (isLazyRequest) {
+if (isLazyRequest && !requestedIsDisabled) {
     for (const loader of COMMAND_LOADERS[requestedCommand])
         await reg(loader);
 }
+// White-label: remove any commands this brand disabled so they resolve as
+// unknown (the command:* handler then reports "unknown command"). Unbranded or
+// nothing-disabled → no-op. Done after all registration paths above.
+if (brandDisabled.size > 0) {
+    const kept = program.commands.filter((c) => !brandDisabled.has(c.name()));
+    if (kept.length !== program.commands.length) {
+        program.commands = kept;
+    }
+}
 // Pure documentation paths (--version / --help / -h) return immediately: skip
 // the update check (PATH scan + cache read) and the detached background sync
 // (spawns a child process) that every other invocation runs.

package/dist/lib/activity.d.ts

@@ -0,0 +1,124 @@
+import type { EventRecord } from './events.js';
+/** Recognizable milestone events, ordered first in any activity lane. */
+export type MilestoneEvent = 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created';
+/** Routine activity events, collapsed to counts by readers. */
+export type ActivityKind = 'file.edited';
+export type ActivityEventKind = MilestoneEvent | ActivityKind;
+export type ActivityTier = 'milestone' | 'activity';
+/** The set of milestone events, for tier classification and ordering. */
+export declare const MILESTONE_EVENTS: readonly MilestoneEvent[];
+export declare function tierForEvent(event: string): ActivityTier;
+export interface ActivityEvent {
+    /** Schema version, for forward-compatible readers. */
+    v: number;
+    /** ISO-8601 timestamp of the event. */
+    ts: string;
+    /** Event kind (see {@link ActivityEventKind}). */
+    event: ActivityEventKind | string;
+    /** Coarse importance tier -- stamped by the writer, recomputed if absent. */
+    tier: ActivityTier;
+    /** Owning session id. */
+    sessionId: string;
+    /** Mailbox id for routing/joins (falls back to sessionId). */
+    mailboxId: string;
+    /** Short, normalized hostname the event fired on. */
+    host: string;
+    /** Runtime label (headless, tmux, cloud, ...). */
+    runtime: string;
+    /** Working directory at event time -- the join key to a project/git repo. */
+    cwd?: string;
+    /** Agent that produced the event (claude, codex, ...). */
+    agent?: string;
+    /** Tool that triggered the event (Bash, Task, ExitPlanMode, ...). */
+    tool?: string;
+    /** One-line human summary (plan title, PR command, sub-agent role). */
+    detail?: string;
+    /** Extracted URL when the event has one (e.g. the opened PR). */
+    url?: string;
+}
+/**
+ * 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 declare function appendActivityEvent(event: Omit<ActivityEvent, 'v' | 'tier'> & {
+    v?: number;
+    tier?: ActivityTier;
+}, root?: string): void;
+/** Read all events for one session (bounded tail). */
+export declare function readSessionActivity(sessionId: string, root?: string, maxBytes?: number): ActivityEvent[];
+/** List session ids that have an activity log. */
+export declare function listActivitySessions(root?: string): string[];
+export interface RecentActivityOptions {
+    /** Only include events at or after this epoch-ms. */
+    sinceMs?: number;
+    /** Cap the number of returned events (most recent first). */
+    limit?: number;
+    /** Override the activity dir (tests). */
+    root?: string;
+    /** Per-session tail budget in bytes. */
+    maxBytesPerSession?: number;
+}
+/**
+ * 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 declare function readRecentActivity(opts?: RecentActivityOptions): ActivityEvent[];
+export interface CollapsedActivity {
+    /** Milestone events, individually preserved, newest first. */
+    milestones: ActivityEvent[];
+    /** Routine events rolled up to counts, e.g. { 'file.edited': 12 }. */
+    counts: Record<string, number>;
+    /** Number of sub-agents spawned across the collapsed set. */
+    subagentCount: number;
+}
+/**
+ * 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 declare function collapseActivity(events: ActivityEvent[]): CollapsedActivity;
+/**
+ * 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.
+ */
+export declare function activityEventToRecord(ev: ActivityEvent): EventRecord;
+/** Read recent activity across sessions as unified {@link EventRecord}s. */
+export declare function readActivityAsEventRecords(opts?: RecentActivityOptions): EventRecord[];
+/** Glyph + color + human label per event, so the lane reads at a glance. */
+export declare const EVENT_STYLE: Record<string, {
+    glyph: string;
+    color: (s: string) => string;
+    label: string;
+}>;
+export declare function styleForEvent(event: string): {
+    glyph: string;
+    color: (s: string) => string;
+    label: string;
+};
+/** One rendered activity line: `  <rel>  [host] <glyph label> detail url`. */
+export declare function formatActivityLine(ev: ActivityEvent, opts?: {
+    showHost?: boolean;
+}): string;
+/**
+ * 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) 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 declare const ACTIVITY_LOG_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Append agent-activity events for `agents feed` / `agents activity`.\n\nBound to PreToolUse (ExitPlanMode, Task) and PostToolUse (Bash, Write, Edit,\nMultiEdit). One append-only file per session; read-only tools never trigger it\nbecause the manifest matcher excludes them.\n\nSub-agent gate: when the payload carries `agent_type`, this is a Task/Agent\nsub-agent -- skip so only the top-level agent logs its own activity.\n\nFail-open: ANY error is swallowed so a logging hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport re\nimport sys\nimport json\nimport shlex\nimport socket\nfrom datetime import datetime, timezone\n\nMAX_LOG_BYTES = 5 * 1024 * 1024  # cap a pathological session's log\nMILESTONE_EVENTS = {\n    \"plan.created\", \"pr.opened\", \"pr.merged\", \"worktree.created\",\n    \"worktree.removed\", \"commit.created\", \"pushed\", \"subagent.spawned\",\n    \"artifact.created\",\n}\n\n# Deliverable file types + locations -- a Write here is a recognizable artifact\n# (an HTML plan, a PDF report, a rendered image), not a routine code edit.\nARTIFACT_EXTS = {\n    \".html\", \".htm\", \".pdf\", \".png\", \".jpg\", \".jpeg\", \".gif\", \".svg\",\n    \".webp\", \".mp4\", \".mov\", \".webm\", \".csv\", \".xlsx\", \".pptx\", \".docx\",\n}\nARTIFACT_DIR_HINTS = (\"/tmp/\", \"/downloads/\", \"/.agents/artifacts/\")\n\n\ndef is_artifact(file_path):\n    low = (file_path or \"\").lower()\n    if os.path.splitext(low)[1] in ARTIFACT_EXTS:\n        return True\n    return any(hint in low for hint in ARTIFACT_DIR_HINTS)\n\n\ndef first_line(text, limit=140):\n    for raw in (text or \"\").splitlines():\n        s = raw.strip().lstrip(\"#\").strip()\n        if s:\n            return s[:limit]\n    return \"\"\n\n\ndef _subcommand(tokens, tool):\n    \"\"\"First non-flag token after `tool`, i.e. its subcommand (skips -C <path>,\n    -c <cfg>, and other leading flags). None if `tool` isn't the invoked command.\"\"\"\n    try:\n        i = tokens.index(tool) + 1\n    except ValueError:\n        return None, []\n    while i < len(tokens):\n        t = tokens[i]\n        if t in (\"-C\", \"-c\", \"--git-dir\", \"--work-tree\"):\n            i += 2  # flag that consumes the next token\n            continue\n        if t.startswith(\"-\"):\n            i += 1\n            continue\n        return t, tokens[i + 1:]\n    return None, []\n\n\ndef classify_bash(command):\n    \"\"\"Return the milestone event for a git/gh command, else None. Tokenizes so a\n    path like `git diff -- src/commit.ts` is not mistaken for a commit.\"\"\"\n    try:\n        tokens = shlex.split(command or \"\")\n    except Exception:\n        tokens = (command or \"\").split()\n\n    verb, rest = _subcommand(tokens, \"git\")\n    if verb == \"worktree\":\n        sub = rest[0] if rest else \"\"\n        if sub == \"add\":\n            return \"worktree.created\"\n        if sub == \"remove\":\n            return \"worktree.removed\"\n    elif verb == \"commit\":\n        return \"commit.created\"\n    elif verb == \"push\":\n        return \"pushed\"\n\n    verb, rest = _subcommand(tokens, \"gh\")\n    if verb == \"pr\" and rest:\n        if rest[0] == \"create\":\n            return \"pr.opened\"\n        if rest[0] == \"merge\":\n            return \"pr.merged\"\n    return None\n\n\ndef extract_url(tool_response):\n    \"\"\"Pull the first https URL out of a Bash tool response (stdout).\"\"\"\n    text = \"\"\n    if isinstance(tool_response, dict):\n        text = str(tool_response.get(\"stdout\") or tool_response.get(\"output\") or \"\")\n    elif isinstance(tool_response, str):\n        text = tool_response\n    m = re.search(r\"https?://\\S+\", text)\n    return m.group(0).rstrip(\").,\") if m else None\n\n\ndef build_event(payload, hook_event):\n    tool_name = payload.get(\"tool_name\", \"\")\n    tool_input = payload.get(\"tool_input\", {}) or {}\n    tool_response = payload.get(\"tool_response\", {})\n\n    event = None\n    detail = None\n    url = None\n\n    if hook_event == \"PreToolUse\":\n        if tool_name == \"ExitPlanMode\":\n            event = \"plan.created\"\n            detail = first_line(tool_input.get(\"plan\", \"\")) or \"plan presented\"\n        elif tool_name == \"Task\":\n            event = \"subagent.spawned\"\n            role = tool_input.get(\"subagent_type\") or \"agent\"\n            desc = tool_input.get(\"description\") or tool_input.get(\"prompt\") or \"\"\n            detail = (role + \": \" + first_line(desc)).strip(\": \").strip()\n    elif hook_event == \"PostToolUse\":\n        if tool_name == \"Bash\":\n            event = classify_bash(tool_input.get(\"command\", \"\"))\n            if event:\n                detail = first_line(tool_input.get(\"command\", \"\"))\n                url = extract_url(tool_response)\n        elif tool_name in (\"Write\", \"Edit\", \"MultiEdit\"):\n            fp = tool_input.get(\"file_path\") or tool_input.get(\"path\") or \"\"\n            # A freshly-written deliverable is a milestone; edits and code\n            # writes stay routine and collapse to a count.\n            if tool_name == \"Write\" and is_artifact(fp):\n                event = \"artifact.created\"\n            else:\n                event = \"file.edited\"\n            detail = os.path.basename(fp) if fp else tool_name\n\n    if not event:\n        return None, tool_name\n\n    tier = \"milestone\" if event in MILESTONE_EVENTS else \"activity\"\n    record = {\n        \"v\": 1,\n        \"ts\": datetime.now(timezone.utc).isoformat(),\n        \"event\": event,\n        \"tier\": tier,\n    }\n    if detail:\n        record[\"detail\"] = detail\n    if url:\n        record[\"url\"] = url\n    record[\"tool\"] = tool_name\n    return record, tool_name\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate -- only the top-level agent logs.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    hook_event = payload.get(\"hook_event_name\", \"\")\n    record, tool_name = build_event(payload, hook_event)\n    if not record:\n        return\n\n    safe_session = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id) or \"unknown\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    activity_dir = os.path.join(home, \".agents\", \".history\", \"activity\")\n    target = os.path.join(activity_dir, safe_session + \".jsonl\")\n\n    # Identity (mirrors 10-feed-publish.py).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", hostname.split(\".\")[0].strip().lower()) or \"unknown\"\n\n    record[\"sessionId\"] = session_id\n    record[\"mailboxId\"] = mailbox_id\n    record[\"host\"] = host\n    record[\"runtime\"] = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n    cwd = payload.get(\"cwd\") or os.environ.get(\"AGENTS_CWD\")\n    if cwd:\n        record[\"cwd\"] = cwd\n    agent = os.environ.get(\"AGENTS_AGENT_NAME\") or \"claude\"\n    record[\"agent\"] = agent\n\n    try:\n        os.makedirs(activity_dir, exist_ok=True)\n        # Cap growth: once over the size limit, keep only milestones.\n        if record[\"tier\"] != \"milestone\":\n            try:\n                if os.path.getsize(target) > MAX_LOG_BYTES:\n                    return\n            except OSError:\n                pass\n        with open(target, \"a\") as f:\n            f.write(json.dumps(record) + \"\\n\")\n    except Exception:\n        pass  # fail open\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
+/** Hook manifest entries (agents.yaml shape) for the activity-log hook. */
+export declare const ACTIVITY_HOOK_DEFINITIONS: Record<string, Record<string, unknown>>;
+/**
+ * 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 declare function ensureActivityLogHook(userAgentsDir?: string): {
+    installed: boolean;
+    error?: string;
+};