@phnx-labs/agents-cli 1.22.6 → 1.22.7

package/dist/lib/session/db.js

@@ -25,7 +25,14 @@ const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 30;
+export const SCHEMA_VERSION = 31;
+/**
+ * Bump to force `agents sessions backfill resources` to re-derive every
+ * session's skill/slash-command tallies on its next run (resource_scan_ledger
+ * rows with a lower version are treated as stale — the same mechanism
+ * TOOL_INDEX_VERSION gives the tool backfill).
+ */
+export const RESOURCE_INDEX_VERSION = 1;
 /**
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
@@ -238,6 +245,25 @@ CREATE TABLE IF NOT EXISTS session_resource_usage (
 );
 CREATE INDEX IF NOT EXISTS idx_session_resource_usage_kind_name ON session_resource_usage(kind, name);
 CREATE INDEX IF NOT EXISTS idx_session_resource_usage_plugin ON session_resource_usage(plugin);
+
+-- One-shot historical backfill bookkeeping for session_resource_usage, mirroring
+-- tool_scan_ledger. The normal incremental scan writes resource usage for every
+-- session it (re)parses, but a session indexed before #12 shipped keeps a fresh
+-- scan_ledger row and is never re-derived — so its skill/slash-command tallies
+-- were never recorded. The "agents sessions backfill resources" command walks
+-- history, re-parses each transcript from byte 0, and stamps coverage here
+-- (mtime + size + extractor_version) so reruns skip completed transcripts. This
+-- is a SCAN LEDGER, not a second copy of the usage data — the usage itself lives
+-- only in session_resource_usage.
+CREATE TABLE IF NOT EXISTS resource_scan_ledger (
+  session_id TEXT PRIMARY KEY,
+  file_path TEXT NOT NULL UNIQUE,
+  file_mtime_ms INTEGER NOT NULL,
+  file_size INTEGER NOT NULL,
+  extractor_version INTEGER NOT NULL,
+  indexed_at INTEGER NOT NULL,
+  resource_count INTEGER NOT NULL
+);
 `;
 let dbInstance = null;
 /**
@@ -678,6 +704,23 @@ function migrateSchema(db, fromVersion) {
         if (!cols.has('used_computer'))
             db.exec(`ALTER TABLE sessions ADD COLUMN used_computer INTEGER`);
     }
+    if (fromVersion < 31) {
+        // v30 → v31: independent ledger for the explicit resource-usage backfill
+        // (agents sessions backfill resources). Do NOT wipe scan_ledger — normal
+        // session listing stays warm; historical resource rows are filled once on
+        // demand, exactly like the tool-index ledger (v25).
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS resource_scan_ledger (
+        session_id TEXT PRIMARY KEY,
+        file_path TEXT NOT NULL UNIQUE,
+        file_mtime_ms INTEGER NOT NULL,
+        file_size INTEGER NOT NULL,
+        extractor_version INTEGER NOT NULL,
+        indexed_at INTEGER NOT NULL,
+        resource_count INTEGER NOT NULL
+      );
+    `);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -1829,6 +1872,10 @@ function buildSessionWhere(options) {
         where.push('LOWER(IFNULL(project, \'\')) LIKE ?');
         params.push(`%${options.project.toLowerCase()}%`);
     }
+    if (options.machine) {
+        where.push('machine = ? COLLATE NOCASE');
+        params.push(options.machine);
+    }
     // id lookup. SQLite's LIKE is case-insensitive for ASCII, so a lowercased
     // pattern matches mixed-case ids; the `=` exact compare adds COLLATE NOCASE
     // for the same reason. short_id carries its own index (idx_sessions_short_id);
@@ -2006,6 +2053,188 @@ export function queryUsageRollup(options) {
   `;
     return db.prepare(sql).all(...params);
 }
+/**
+ * Roll up skill / slash-command usage from session_resource_usage, joined to
+ * `sessions` for attribution so the same filter shape as querySessions
+ * (agent / project / since / machine) narrows WHICH sessions count. Grouped by
+ * resource identity (kind + name + plugin + source) and ordered by invocation
+ * volume — the read side of "which skills/commands do I actually use, and which
+ * are dead weight". `order: 'bottom'` ranks least-used first (the one-time
+ * skills); `limit` caps the returned rows.
+ *
+ * The signal only captures EXPLICIT invocations (slash commands and `Skill`
+ * tool calls). An auto-triggered skill (loaded by description match) emits no
+ * event, so it reads as zero here — a 0 means "never explicitly invoked", not
+ * "never loaded". Skill invocations are recorded for Claude and Kimi (the
+ * `Skill`-tool harnesses); slash-commands are Claude-only.
+ *
+ * `kind` / `pluginFilter` filter the RESOURCE rows directly (r.kind / r.plugin),
+ * distinct from QueryOptions.skill / QueryOptions.plugin, which filter SESSIONS
+ * — deliberately not routed through buildSessionWhere so `--plugin rush` shows
+ * only rush's resources rather than every resource used by a rush-touching
+ * session.
+ */
+export function queryResourceUsageStats(options) {
+    const db = getDB();
+    const { clause, params } = buildSessionWhere(options);
+    // buildSessionWhere emits bare column names (agent, timestamp, machine, …) and
+    // `id IN (…)` subqueries; in this join they resolve unambiguously to `sessions`
+    // (session_resource_usage carries none of those columns, and its key is
+    // session_id, not id). Strip the leading WHERE so resource predicates append.
+    const base = clause.replace(/^WHERE\s+/, '');
+    const preds = base ? [base] : [];
+    const allParams = [...params];
+    if (options.kind) {
+        preds.push('r.kind = ?');
+        allParams.push(options.kind);
+    }
+    if (options.pluginFilter) {
+        preds.push('r.plugin = ? COLLATE NOCASE');
+        allParams.push(options.pluginFilter);
+    }
+    const whereClause = preds.length ? `WHERE ${preds.join(' AND ')}` : '';
+    const direction = options.order === 'bottom' ? 'ASC' : 'DESC';
+    const limitClause = options.limit ? `LIMIT ${Math.max(1, Math.floor(options.limit))}` : '';
+    // Group by resource IDENTITY = (kind, name) only, per SES-IF-4b. name already
+    // embeds the `plugin:short` prefix for a plugin resource, so (kind, name) is
+    // the true identity. plugin and source are PROVENANCE, not identity, and drift
+    // per session — the same `rush:design` resolves plugin='rush' in a session
+    // whose cwd discovered the plugin and plugin=NULL in one that didn't, and the
+    // layer a flat resource resolved to varies (user vs system). Grouping on either
+    // would split one resource into fractional rows. Aggregate both with MAX so the
+    // row carries a representative (non-NULL when any session resolved it) label
+    // while the counts stay whole.
+    const sql = `
+    SELECT
+      r.kind AS kind,
+      r.name AS name,
+      MAX(r.plugin) AS plugin,
+      MAX(r.source) AS source,
+      COUNT(DISTINCT r.session_id) AS sessions,
+      SUM(r.count) AS invocations
+    FROM session_resource_usage r
+    JOIN sessions s ON s.id = r.session_id
+    ${whereClause}
+    GROUP BY r.kind, r.name
+    ORDER BY invocations ${direction}, sessions ${direction}, r.name ASC
+    ${limitClause}
+  `;
+    return db.prepare(sql).all(...allParams);
+}
+/**
+ * Coverage of the resource-usage signal: how many distinct sessions carry any
+ * row in session_resource_usage vs. the total indexed. A low ratio means the
+ * historical backfill (`agents sessions backfill resources`) hasn't run — the
+ * stats surface uses this to tell the user their zero-counts may just be
+ * un-scanned history, not genuine non-use.
+ */
+export function resourceUsageCoverage() {
+    const db = getDB();
+    const covered = db.prepare(`SELECT COUNT(DISTINCT session_id) AS n FROM session_resource_usage`).get().n;
+    const total = db.prepare(`SELECT COUNT(*) AS n FROM sessions`).get().n;
+    return { covered, total };
+}
+/** Has this session's resource usage been derived at the current extractor version for this exact file? */
+function needsResourceIndex(db, sessionId, stamp) {
+    const row = db
+        .prepare(`SELECT file_mtime_ms, file_size, extractor_version FROM resource_scan_ledger WHERE session_id = ?`)
+        .get(sessionId);
+    return !row
+        || row.file_mtime_ms !== stamp.fileMtimeMs
+        || row.file_size !== stamp.fileSize
+        || row.extractor_version !== RESOURCE_INDEX_VERSION;
+}
+/** Record that a session's resource usage is current at RESOURCE_INDEX_VERSION for this file stamp. */
+function stampResourceLedger(db, sessionId, filePath, stamp, resourceCount) {
+    db.prepare(`
+    INSERT INTO resource_scan_ledger
+      (session_id, file_path, file_mtime_ms, file_size, extractor_version, indexed_at, resource_count)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id) DO UPDATE SET
+      file_path = excluded.file_path,
+      file_mtime_ms = excluded.file_mtime_ms,
+      file_size = excluded.file_size,
+      extractor_version = excluded.extractor_version,
+      indexed_at = excluded.indexed_at,
+      resource_count = excluded.resource_count
+  `).run(sessionId, filePath, stamp.fileMtimeMs, stamp.fileSize, RESOURCE_INDEX_VERSION, Date.now(), resourceCount);
+}
+/**
+ * One-shot historical backfill of session_resource_usage (#12). The normal
+ * incremental scan writes resource usage only for sessions whose transcript it
+ * (re)parses; a session indexed before this feature shipped keeps a fresh
+ * scan_ledger row and is never re-derived, so its skill/slash-command tallies
+ * were never recorded. This walks the session index, re-parses each transcript
+ * FROM BYTE 0 (parseSession fully materializes — no resumable cursor, so
+ * claude/codex re-derive their tallies from scratch), writes the usage, and
+ * stamps resource_scan_ledger so reruns skip completed transcripts — the same
+ * independent-ledger shape `agents sessions backfill tools` uses.
+ *
+ * Harness-agnostic: parseSession + extractSkills/extractSlashCommands cover
+ * every agent uniformly, so there is no per-harness branch to keep in parity.
+ * Synthetic rows without a transcript (OpenClaw channels/cron) are skipped.
+ */
+export function backfillResourceUsage(filter = {}, onProgress) {
+    const db = getDB();
+    // No LIMIT: the backfill covers the whole matching history. skipExistenceCheck
+    // stays off so vanished transcripts are dropped, matching querySessions.
+    const sessions = querySessions({ ...filter, limit: undefined });
+    const result = { scanned: 0, updated: 0, skipped: 0, failed: 0, resourceRows: 0 };
+    let done = 0;
+    for (const meta of sessions) {
+        if (!meta.filePath) {
+            done++;
+            onProgress?.(done, sessions.length);
+            continue;
+        }
+        result.scanned++;
+        let stamp;
+        try {
+            const st = fs.statSync(meta.filePath);
+            stamp = { fileMtimeMs: st.mtimeMs, fileSize: st.size };
+        }
+        catch {
+            result.failed++;
+            done++;
+            onProgress?.(done, sessions.length);
+            continue;
+        }
+        if (!needsResourceIndex(db, meta.id, stamp)) {
+            result.skipped++;
+            done++;
+            onProgress?.(done, sessions.length);
+            continue;
+        }
+        try {
+            const events = parseSession(meta.filePath, meta.agent);
+            // Fail loud on a bad read. writeResourceUsage DELETEs the session's rows
+            // before it re-inserts, so a transcript that parses to ZERO events (a
+            // truncated / mid-sync / corrupt file — parseSession returns [] instead of
+            // throwing) would silently wipe real historical usage and then stamp the
+            // ledger "current", masking the loss. A completed historical transcript
+            // always has turns, so an empty parse is never a legitimate "this session
+            // used nothing" — it is an unreadable file. Skip it (count as failed, leave
+            // the ledger unstamped) so a later good read retries.
+            if (events.length === 0) {
+                result.failed++;
+                done++;
+                onProgress?.(done, sessions.length);
+                continue;
+            }
+            writeResourceUsage(meta.id, events, meta.cwd);
+            const rows = db.prepare(`SELECT COUNT(*) AS n FROM session_resource_usage WHERE session_id = ?`).get(meta.id).n;
+            stampResourceLedger(db, meta.id, meta.filePath, stamp, rows);
+            result.updated++;
+            result.resourceRows += rows;
+        }
+        catch {
+            result.failed++;
+        }
+        done++;
+        onProgress?.(done, sessions.length);
+    }
+    return result;
+}
 /**
  * Map every team name to the session that ran `agents teams create/add` for it.
  *

package/dist/lib/session/digest.d.ts

@@ -45,7 +45,7 @@ export declare function toolHistogram(toolCounts: Record<string, number>, top?:
 /**
  * Aggregate recognized external tools invoked via Bash across a session.
  * Unknown one-off commands are bucketed as `other` so the ranking surface
- * (e.g. `agents activity --tools`) only surfaces repeatable tools.
+ * only surfaces repeatable tools.
  */
 export declare function bashToolCounts(events: SessionEvent[]): Record<string, number>;
 export interface TestResult {

package/dist/lib/session/digest.js

@@ -131,7 +131,7 @@ export function toolHistogram(toolCounts, top = 8) {
 /**
  * Aggregate recognized external tools invoked via Bash across a session.
  * Unknown one-off commands are bucketed as `other` so the ranking surface
- * (e.g. `agents activity --tools`) only surfaces repeatable tools.
+ * only surfaces repeatable tools.
  */
 export function bashToolCounts(events) {
     const counts = {};

package/dist/lib/share/publish.js

@@ -81,6 +81,30 @@ function guessContentType(filePath) {
         return 'application/json';
     if (/\.svg$/i.test(filePath))
         return 'image/svg+xml';
+    // Raster images + video: agents publish screenshots and screen recordings as PR
+    // evidence, and GitHub's image proxy (camo) only renders an inline `![](url)` when
+    // the asset is served with a real image/video content-type — octet-stream is
+    // refused. Type them so the share URL embeds instead of downloading.
+    if (/\.png$/i.test(filePath))
+        return 'image/png';
+    if (/\.jpe?g$/i.test(filePath))
+        return 'image/jpeg';
+    if (/\.gif$/i.test(filePath))
+        return 'image/gif';
+    if (/\.webp$/i.test(filePath))
+        return 'image/webp';
+    if (/\.avif$/i.test(filePath))
+        return 'image/avif';
+    if (/\.ico$/i.test(filePath))
+        return 'image/x-icon';
+    if (/\.mp4$/i.test(filePath))
+        return 'video/mp4';
+    if (/\.mov$/i.test(filePath))
+        return 'video/quicktime';
+    if (/\.webm$/i.test(filePath))
+        return 'video/webm';
+    if (/\.pdf$/i.test(filePath))
+        return 'application/pdf';
     if (/\.txt$|\.md$/i.test(filePath))
         return 'text/plain; charset=utf-8';
     return 'application/octet-stream';

package/dist/lib/startup/command-registry.d.ts

@@ -97,7 +97,6 @@ export declare const loadCloud: ModuleLoader;
 export declare const loadMessage: ModuleLoader;
 export declare const loadSend: ModuleLoader;
 export declare const loadFeed: ModuleLoader;
-export declare const loadActivity: ModuleLoader;
 export declare const loadMailboxes: ModuleLoader;
 export declare const loadServe: ModuleLoader;
 export declare const loadShare: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -75,7 +75,6 @@ export const loadCloud = async () => (await import('../../commands/cloud.js')).r
 export const loadMessage = async () => (await import('../../commands/message.js')).registerMessageCommand;
 export const loadSend = async () => (await import('../../commands/send.js')).registerSendCommand;
 export const loadFeed = async () => (await import('../../commands/feed.js')).registerFeedCommand;
-export const loadActivity = async () => (await import('../../commands/activity.js')).registerActivityCommand;
 export const loadMailboxes = async () => (await import('../../commands/mailboxes.js')).registerMailboxesCommand;
 export const loadServe = async () => (await import('../../commands/serve.js')).registerServeCommand;
 export const loadShare = async () => (await import('../../commands/share.js')).registerShareCommands;
@@ -199,7 +198,6 @@ export const COMMAND_LOADERS = {
     send: [loadSend],
     notify: [loadSend],
     feed: [loadFeed],
-    activity: [loadActivity],
     mailboxes: [loadMailboxes],
     mailbox: [loadMailboxes],
     serve: [loadServe],

package/dist/lib/subagents-registry.js

@@ -252,6 +252,9 @@ export const SUBAGENT_TARGETS = {
     // Tier 1 -- flat markdown, Claude-compatible flatten.
     claude: flatFile({ subdir: ['.claude', 'agents'], ext: '.md', transform: transformSubagentForClaude }),
     grok: flatFile({ subdir: ['.grok', 'agents'], ext: '.md', transform: transformSubagentForClaude }),
+    // Oh My Pi discovers Claude-shaped agent markdown from ~/.omp/agent/agents/
+    // (`omp agents unpack` writes there); frontmatter name/description + body.
+    pi: flatFile({ subdir: ['.omp', 'agent', 'agents'], ext: '.md', transform: transformSubagentForClaude, readMeta: metaFrontmatterFallback }),
     droid: flatFile({ subdir: ['.factory', 'droids'], ext: '.md', transform: transformSubagentForDroid }),
     // Bespoke frontmatter/format, still one flat file.
     codex: flatFile({ subdir: ['.codex', 'agents'], ext: '.toml', transform: transformSubagentForCodex }),

package/dist/lib/types.d.ts

@@ -8,7 +8,7 @@
 import type { CloudProviderId } from './cloud/types.js';
 import type { FeedBroadcastConfig } from './feed-broadcast.js';
 /** Unique identifier for a current or legacy AI coding agent. */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'pi';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
 /**
@@ -196,6 +196,15 @@ export interface AgentConfig {
          * rules file (inline all @-imports) when syncing it into the version home.
          */
         rulesImports?: boolean;
+        /**
+         * Whether the agent can open an interactive REPL session when launched with
+         * NO prompt (bare invocation). Agents whose CLI exits immediately without a
+         * prompt (e.g. cursor-agent) must declare `false` here; agents that open a
+         * TUI/REPL with no args declare `true`. Used by the `auto` harness picker
+         * to avoid routing a prompt-less interactive run to a harness that would
+         * exit silently (RUSH-2185, EXEC-23a).
+         */
+        interactiveRepl?: Capability;
     };
 }
 /**
@@ -213,7 +222,7 @@ export type RulesCapability = false | {
     file: string;
 };
 /** Names of every gateable capability on AgentConfig. */
-export type CapabilityName = 'hooks' | 'mcp' | 'mcpHttp' | 'mcpHeaders' | 'allowlist' | 'skills' | 'commands' | 'plugins' | 'subagents' | 'rules' | 'workflows' | 'memory';
+export type CapabilityName = 'hooks' | 'mcp' | 'mcpHttp' | 'mcpHeaders' | 'allowlist' | 'skills' | 'commands' | 'plugins' | 'subagents' | 'rules' | 'workflows' | 'memory' | 'interactiveRepl';
 /**
  * Permission modes controlling agent autonomy.
  *   plan  read-only investigation; no writes, no shell side-effects

package/dist/lib/usage.d.ts

@@ -177,6 +177,7 @@ export declare const USAGE_FETCH_CONCURRENCY = 3;
  * minutes; that re-fired too often when delayed responses stacked.
  */
 export declare const USAGE_CACHE_FRESH_MS: number;
+export declare const USAGE_CACHE_SWR_MS: number;
 /**
  * Unified entry for every multi-account usage lookup (`agents view`, rotation,
  * JSON export). Deduplicates by usage identity, then fans out through the
@@ -491,6 +492,10 @@ export declare function writeClaudeUsageCache(usageKey: string, snapshot: UsageS
  * Returns true only when a valid access token can be obtained.
  */
 export declare function isClaudeAuthValid(home?: string): Promise<boolean>;
+/** Render a colored block-character progress bar. */
+export declare function renderBar(usedPercent: number, length: number, minimumVisible?: number): string;
+/** Return a chalk color function based on the usage percentage threshold. */
+export declare function getUsageColor(usedPercent: number): (text: string) => string;
 /** Parse the latest billing info from Grok's unified log. */
 declare function getGrokUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
 /** Per-model bucket in Cursor's /api/usage response. */

package/dist/lib/usage.js

@@ -219,7 +219,7 @@ const USAGE_BG_REFRESH_CONCURRENCY = 2;
  * minutes; that re-fired too often when delayed responses stacked.
  */
 export const USAGE_CACHE_FRESH_MS = 5 * 60 * 1000;
-const USAGE_CACHE_SWR_MS = 24 * 60 * 60 * 1000; // 24 hours — beyond this, block on live fetch.
+export const USAGE_CACHE_SWR_MS = 24 * 60 * 60 * 1000; // 24 hours — beyond this, block on live fetch.
 /**
  * Unified entry for every multi-account usage lookup (`agents view`, rotation,
  * JSON export). Deduplicates by usage identity, then fans out through the
@@ -1696,7 +1696,7 @@ function renderCompactUsageBar(usedPercent) {
     return renderBar(usedPercent, COMPACT_BAR_LEN, usedPercent > 0 ? 1 : 0);
 }
 /** Render a colored block-character progress bar. */
-function renderBar(usedPercent, length, minimumVisible = 0) {
+export function renderBar(usedPercent, length, minimumVisible = 0) {
     const rounded = Math.round((usedPercent / 100) * length);
     const filled = Math.max(minimumVisible, Math.max(0, Math.min(length, rounded)));
     const color = getUsageColor(usedPercent);
@@ -1707,7 +1707,7 @@ function colorUsage(text, usedPercent) {
     return getUsageColor(usedPercent)(text);
 }
 /** Return a chalk color function based on the usage percentage threshold. */
-function getUsageColor(usedPercent) {
+export function getUsageColor(usedPercent) {
     if (usedPercent >= 100)
         return chalk.red;
     if (usedPercent >= 80)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.6",
+  "version": "1.22.7",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",

package/dist/commands/activity.d.ts

@@ -1,87 +0,0 @@
-/**
- * `agents activity` -- the agent-activity lane: a running stream of what agents
- * DID (plan created, PR opened, worktree created, sub-agent spawned, files
- * edited), read from the append-only per-session activity logs.
- *
- * Complements `agents feed` (what agents are WAITING on). Events are emitted at
- * hook time by 11-activity-log.py, so this reader never re-parses transcripts --
- * it tails the logs and collapses routine work to counts, surfacing milestones
- * individually and newest-first.
- *
- * Fleet-wide and project-grouped BY DEFAULT: the question this command answers
- * is "what are my agents doing", and agents run on every box, so a local-only
- * flat stream answered a narrower question than anyone asked. Each run fans the
- * same `activity --json` payload out across the fleet the way `agents feed`
- * does, merges every peer's stream host-tagged, joins each item to live sessions
- * (project / ticket / execution host), and buckets it by project -- one level,
- * no sub-grouping, with the machines named in each project's header.
- *
- * `--local` scopes back to this machine, `--host <box>` to named peers, and
- * `--flat` (or `--group-by none`) restores the single newest-first stream.
- */
-import type { Command } from 'commander';
-import { type ActivityGroupBy } from '../lib/activity.js';
-/** Recursion guard: a peer answering a fan-out never re-fans-out itself. */
-export declare const ACTIVITY_NO_FANOUT_ENV = "AGENTS_ACTIVITY_LOCAL";
-interface ActivityOpts {
-    json?: boolean;
-    all?: boolean;
-    milestones?: boolean;
-    limit: number;
-    since?: number;
-    local?: boolean;
-    host?: string[];
-    device?: string[];
-    devicesAll?: boolean;
-    hostsAll?: boolean;
-    groupBy?: string;
-    flat?: boolean;
-    project?: string;
-    filter?: string;
-}
-/**
- * Does this hook-registration error concern one of the activity-log hooks?
- * `registerHooksToSettings` prefixes each error with the manifest hook name
- * (`<name>: script not found`), so the entry names are the discriminator.
- */
-export declare function isActivityHookError(error: string): boolean;
-/**
- * Is this error attributable to a named manifest hook at all? Errors that name
- * no hook — `Failed to parse settings.json`, `Failed to write
- * agents-cli-hooks.ts: …` — are agent-level aborts, not per-hook noise, and
- * must never be filtered out.
- */
-export declare function isManifestHookError(error: string, manifestNames: string[]): boolean;
-/**
- * One compact trailing note for peers that didn't answer the fan-out. Now that
- * every run dials the fleet, an offline box is routine -- but never silent: the
- * reader has to know the timeline is missing a machine, not that the machine
- * was idle. Empty string when everything answered.
- */
-export declare function formatUnreachableNote(skipped: string[]): string;
-/**
- * Resolve `--group-by` / `--flat` into the grouping dimension, or `undefined`
- * for a flat stream. Throws on an unknown value so the caller can exit 1 --
- * a mistyped dimension must not silently fall back to the default.
- */
-export declare function resolveActivityGrouping(opts: Pick<ActivityOpts, 'groupBy' | 'flat'>): ActivityGroupBy | undefined;
-/** Which machines an invocation reads from. Pure -- no SSH, no device registry. */
-export interface ActivityScope {
-    /** Read this box's own activity logs. */
-    includeLocal: boolean;
-    /** Dial peers over SSH. */
-    wantRemote: boolean;
-    /** Peers to dial; `undefined` means "every reachable device". */
-    remoteHosts?: string[];
-}
-/**
- * Decide the read scope. Fleet-wide is the DEFAULT -- agents run on every box,
- * so "what are my agents doing" is a fleet question -- and three things narrow
- * it: `--local`, an explicit `--host`/`--device` list, and the recursion guard
- * a peer answering a fan-out carries (else every peer would re-fan the fleet).
- * `--devices-all`/`--hosts-all` are kept as explicit no-ops for scripts that
- * already pass them.
- */
-export declare function resolveActivityScope(opts: Pick<ActivityOpts, 'local' | 'host'>, self: string, noFanoutEnv?: boolean): ActivityScope;
-export declare function registerActivityCommand(program: Command): void;
-export {};