@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/lib/feed-post.d.ts

@@ -0,0 +1,63 @@
+import { type ActivityEvent } from './activity.js';
+import { type PidSessionEntry } from './session/pid-registry.js';
+/** Soft cap so a runaway agent can't flood the activity lane with essays. */
+export declare const STATUS_POST_MAX_CHARS = 500;
+export interface FeedPostInput {
+    /** Human-readable progress text (required). Domain-agnostic free text. */
+    text: string;
+    /** Override session id (escape hatch for scripts/tests). Prefer auto-resolve. */
+    sessionId?: string;
+    /** Override activity root (tests). */
+    activityRoot?: string;
+    /** Override env for identity resolution (tests). */
+    env?: NodeJS.ProcessEnv;
+    /** Override cwd stamp (defaults to process.cwd() / env). */
+    cwd?: string;
+    /** Fixed timestamp (tests). */
+    ts?: string;
+    /**
+     * Starting pid for registry ancestor walk (defaults to process.ppid so the
+     * walk begins at the parent of this CLI process — usually the agent/shell).
+     * Tests inject a fake pid here.
+     */
+    startPid?: number;
+    /** Override parent-pid lookup (tests). */
+    getParentPid?: (pid: number) => number | undefined;
+    /** Override registry read (tests). */
+    readEntry?: (pid: number) => PidSessionEntry | undefined;
+    /** Override full registry list for launchId match (tests). */
+    listEntries?: () => PidSessionEntry[];
+}
+export interface FeedPostResult {
+    event: ActivityEvent;
+}
+export interface PostIdentity {
+    sessionId: string;
+    mailboxId: string;
+    host: string;
+    runtime: string;
+    agent?: string;
+    cwd?: string;
+    pid?: number;
+    launchId?: string;
+    terminalId?: string;
+    tmuxPane?: string;
+}
+/**
+ * Resolve who is posting. Order:
+ *  1. Explicit --session flag
+ *  2. Env: AGENT_SESSION_ID / AGENTS_SESSION_ID / basename(AGENTS_MAILBOX_DIR)
+ *  3. Env AGENT_LAUNCH_ID → match in pid registry
+ *  4. Walk parent PIDs from startPid (default process.ppid) through by-pid registry
+ */
+export declare function resolvePostIdentity(input: Pick<FeedPostInput, 'sessionId' | 'env' | 'cwd' | 'startPid' | 'getParentPid' | 'readEntry' | 'listEntries'>): PostIdentity | undefined;
+/** Walk up to 16 ancestors looking for a by-pid registry entry with a session. */
+export declare function walkPidRegistry(startPid: number, getParent: (pid: number) => number | undefined, readEntry: (pid: number) => PidSessionEntry | undefined): PidSessionEntry | undefined;
+/** Best-effort parent pid of `pid` (Linux /proc, else `ps`). */
+export declare function parentPidOf(pid: number): number | undefined;
+export declare function normalizeStatusText(text: string): string;
+/**
+ * Append a `status.posted` milestone for the calling agent.
+ * Throws if text is empty or session identity cannot be resolved.
+ */
+export declare function postFeedStatus(input: FeedPostInput): FeedPostResult;

package/dist/lib/feed-post.js

@@ -0,0 +1,204 @@
+/**
+ * Agent status posts — deliberate progress messages into the activity stream.
+ *
+ * Surface: `agents feed post <text>` (agent-callable; humans watch via
+ * `agents feed` / `agents activity` / `agents events --module activity`).
+ *
+ * Identity is automatic: session id, agent, cwd, launch/pid/tmux provenance
+ * are resolved from the process environment and the per-pid launch registry
+ * (`lib/session/pid-registry.ts`). The agent only authors free-form text —
+ * no domain-specific flags (tickets, URLs, tracks).
+ *
+ * Storage: append-only activity log as a `status.posted` milestone. Does NOT
+ * open a feed block (blocks remain "needs you" state only).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { appendActivityEvent, } from './activity.js';
+import { machineId } from './machine-id.js';
+import { isValidMailboxId } from './mailbox.js';
+import { listPidSessionEntries, readPidSessionEntry, } from './session/pid-registry.js';
+/** Soft cap so a runaway agent can't flood the activity lane with essays. */
+export const STATUS_POST_MAX_CHARS = 500;
+/**
+ * Resolve who is posting. Order:
+ *  1. Explicit --session flag
+ *  2. Env: AGENT_SESSION_ID / AGENTS_SESSION_ID / basename(AGENTS_MAILBOX_DIR)
+ *  3. Env AGENT_LAUNCH_ID → match in pid registry
+ *  4. Walk parent PIDs from startPid (default process.ppid) through by-pid registry
+ */
+export function resolvePostIdentity(input) {
+    const env = input.env ?? process.env;
+    const readEntry = input.readEntry ?? readPidSessionEntry;
+    const listEntries = input.listEntries ?? listPidSessionEntries;
+    const getParent = input.getParentPid ?? parentPidOf;
+    const envSession = firstValidId([
+        input.sessionId,
+        env.AGENT_SESSION_ID,
+        env.AGENTS_SESSION_ID,
+        mailboxIdFromEnv(env),
+    ]);
+    const launchId = env.AGENT_LAUNCH_ID?.trim() || undefined;
+    let registry;
+    if (launchId) {
+        registry = listEntries().find((e) => e.launchId === launchId);
+    }
+    if (!registry) {
+        const start = input.startPid ?? (typeof process.ppid === 'number' ? process.ppid : undefined);
+        if (start && start > 1) {
+            registry = walkPidRegistry(start, getParent, readEntry);
+        }
+    }
+    // Prefer env session (explicit + managed run), fill gaps from registry.
+    const sessionId = envSession ?? registry?.sessionId;
+    if (!sessionId || !isValidMailboxId(sessionId))
+        return undefined;
+    const mailboxFromEnv = mailboxIdFromEnv(env);
+    const mailboxId = mailboxFromEnv && isValidMailboxId(mailboxFromEnv)
+        ? mailboxFromEnv
+        : sessionId;
+    return {
+        sessionId,
+        mailboxId,
+        host: machineIdFromEnv(env),
+        runtime: env.AGENTS_RUNTIME?.trim() || 'headless',
+        agent: env.AGENTS_AGENT_NAME?.trim()
+            || registry?.agent
+            || detectAgentKind(env),
+        cwd: input.cwd
+            ?? (env.AGENTS_CWD?.trim() || registry?.cwd || process.cwd()),
+        pid: registry?.pid,
+        launchId: launchId || registry?.launchId,
+        terminalId: env.AGENT_TERMINAL_ID?.trim() || registry?.terminalId,
+        tmuxPane: env.TMUX_PANE?.trim() || registry?.tmuxPane,
+    };
+}
+function firstValidId(candidates) {
+    for (const raw of candidates) {
+        const id = (raw ?? '').trim();
+        if (id && isValidMailboxId(id))
+            return id;
+    }
+    return undefined;
+}
+function mailboxIdFromEnv(env) {
+    const dir = env.AGENTS_MAILBOX_DIR?.trim();
+    if (!dir)
+        return undefined;
+    const base = path.basename(dir.replace(/[/\\]+$/, ''));
+    return base || undefined;
+}
+/** Walk up to 16 ancestors looking for a by-pid registry entry with a session. */
+export function walkPidRegistry(startPid, getParent, readEntry) {
+    let pid = startPid;
+    const seen = new Set();
+    let firstHit;
+    for (let i = 0; i < 16 && pid && pid > 1 && !seen.has(pid); i++) {
+        seen.add(pid);
+        const entry = readEntry(pid);
+        if (entry) {
+            if (entry.sessionId && isValidMailboxId(entry.sessionId))
+                return entry;
+            if (!firstHit)
+                firstHit = entry;
+        }
+        pid = getParent(pid);
+    }
+    // Entry without sessionId still carries agent/cwd/launchId — usable when
+    // session id comes from env.
+    return firstHit;
+}
+/** Best-effort parent pid of `pid` (Linux /proc, else `ps`). */
+export function parentPidOf(pid) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return undefined;
+    if (process.platform === 'linux') {
+        try {
+            const status = fs.readFileSync(`/proc/${pid}/status`, 'utf8');
+            const m = status.match(/^PPid:\s*(\d+)/m);
+            if (m) {
+                const pp = Number(m[1]);
+                return Number.isInteger(pp) && pp > 0 ? pp : undefined;
+            }
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    try {
+        const r = spawnSync('ps', ['-o', 'ppid=', '-p', String(pid)], {
+            encoding: 'utf8',
+            timeout: 1000,
+        });
+        if (r.status === 0) {
+            const pp = Number((r.stdout || '').trim());
+            return Number.isInteger(pp) && pp > 0 ? pp : undefined;
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    return undefined;
+}
+export function normalizeStatusText(text) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    if (!collapsed)
+        return '';
+    if (collapsed.length <= STATUS_POST_MAX_CHARS)
+        return collapsed;
+    return `${collapsed.slice(0, STATUS_POST_MAX_CHARS - 1)}…`;
+}
+/**
+ * Append a `status.posted` milestone for the calling agent.
+ * Throws if text is empty or session identity cannot be resolved.
+ */
+export function postFeedStatus(input) {
+    const detail = normalizeStatusText(input.text);
+    if (!detail) {
+        throw new Error('Status text is empty. Usage: agents feed post "what just happened"');
+    }
+    const identity = resolvePostIdentity(input);
+    if (!identity) {
+        throw new Error('No session id. Run from an agents-cli session '
+            + '(AGENT_SESSION_ID / AGENTS_MAILBOX_DIR / pid registry), or pass --session <id>.');
+    }
+    const event = {
+        ts: input.ts ?? new Date().toISOString(),
+        event: 'status.posted',
+        sessionId: identity.sessionId,
+        mailboxId: identity.mailboxId,
+        host: identity.host,
+        runtime: identity.runtime,
+        cwd: identity.cwd,
+        agent: identity.agent,
+        tool: 'feed.post',
+        detail,
+        ...(identity.pid !== undefined ? { pid: identity.pid } : {}),
+        ...(identity.launchId ? { launchId: identity.launchId } : {}),
+        ...(identity.terminalId ? { terminalId: identity.terminalId } : {}),
+        ...(identity.tmuxPane ? { tmuxPane: identity.tmuxPane } : {}),
+    };
+    appendActivityEvent(event, input.activityRoot);
+    return {
+        event: {
+            v: 1,
+            tier: 'milestone',
+            ...event,
+        },
+    };
+}
+function machineIdFromEnv(env) {
+    const raw = env.AGENTS_SYNC_MACHINE_ID || undefined;
+    if (raw) {
+        return raw.split('.')[0].trim().toLowerCase().replace(/[^a-z0-9_-]/g, '-') || 'unknown';
+    }
+    return machineId();
+}
+function detectAgentKind(env) {
+    if (env.CLAUDECODE === '1')
+        return 'claude';
+    if (env.CODEX_CI || env.CODEX_HOME)
+        return 'codex';
+    return 'agent';
+}

package/dist/lib/fleet/apply.d.ts

@@ -11,6 +11,30 @@ import type { DeviceProfile } from '../devices/registry.js';
 import type { DeviceDesired, DeviceProbe, DeviceDiff, FleetAction, FleetPlan, AuthFilePayload } from './types.js';
 /** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
 export declare function agentIdOf(spec: string): string;
+/**
+ * The explicit pinned version of a spec, or undefined for an id-level spec.
+ * `claude@2.1.170` -> `2.1.170`; `claude`, `claude@latest`, `claude@oldest`, and
+ * `claude@all` all return undefined (the label channels install-latest / are
+ * expanded upstream, so they diff at id granularity, not per-version).
+ */
+export declare function pinnedVersion(spec: string): string | undefined;
+/** True when any spec in the roster pins an explicit version (needs a version probe). */
+export declare function rosterNeedsVersions(desired: DeviceDesired[]): boolean;
+/**
+ * Expand any `<agent>@all` spec into one pinned spec per version installed on the
+ * source, so `--agent claude@all` replicates THIS machine's exact version set.
+ * `versionsOf` returns the source's installed versions for an agent id. Every
+ * other spec passes through unchanged; the result is de-duplicated in order.
+ * Throws if `@all` names an agent with no installed versions here (nothing to
+ * replicate — a clear misconfig, not a silent no-op).
+ */
+export declare function expandAllSpecs(specs: string[], versionsOf: (id: string) => string[]): string[];
+/**
+ * Parse `agents view --json` (the all-agents array form) into a map of agent id
+ * -> installed version strings. Tolerant: returns undefined on any parse failure
+ * so a version-pinned spec falls back to id-level presence rather than crashing.
+ */
+export declare function parseInstalledVersions(stdout: string): Record<string, string[]> | undefined;
 /** Source-side auth availability, computed once from `snapshotAuth`. */
 export interface SourceAuth {
     /** Agent ids the source has a readable, propagatable credential file for. */
@@ -37,8 +61,14 @@ export interface DiffContext {
 }
 /** Pure: desired vs probed -> per-device diff + flat action list. */
 export declare function diffFleet(desired: DeviceDesired[], probes: Map<string, DeviceProbe>, ctx: DiffContext): FleetPlan;
-/** Probe one device: reachability + agents-cli version + installed agent ids. */
-export declare function probeDevice(device: DeviceProfile): DeviceProbe;
+export interface ProbeOptions {
+    /** Also fetch per-agent installed versions (one extra `agents view --json`
+     * round-trip). Enable only when the plan has a version-pinned spec. */
+    withVersions?: boolean;
+}
+/** Probe one device: reachability + agents-cli version + installed agent ids
+ * (and, when `withVersions`, the installed version strings per agent). */
+export declare function probeDevice(device: DeviceProfile, opts?: ProbeOptions): DeviceProbe;
 export interface ApplyStep {
     kind: FleetAction['kind'];
     ok: boolean;

package/dist/lib/fleet/apply.js

@@ -17,6 +17,76 @@ import { isPropagatableAgent, KEYCHAIN_BOUND_ON_MAC, buildAuthBundle, } from './
 export function agentIdOf(spec) {
     return spec.split('@')[0].trim();
 }
+/**
+ * The explicit pinned version of a spec, or undefined for an id-level spec.
+ * `claude@2.1.170` -> `2.1.170`; `claude`, `claude@latest`, `claude@oldest`, and
+ * `claude@all` all return undefined (the label channels install-latest / are
+ * expanded upstream, so they diff at id granularity, not per-version).
+ */
+export function pinnedVersion(spec) {
+    const at = spec.indexOf('@');
+    if (at < 0)
+        return undefined;
+    const v = spec.slice(at + 1).trim();
+    if (!v || v === 'latest' || v === 'oldest' || v === 'all')
+        return undefined;
+    return v;
+}
+/** True when any spec in the roster pins an explicit version (needs a version probe). */
+export function rosterNeedsVersions(desired) {
+    return desired.some((d) => d.agents.some((s) => pinnedVersion(s) !== undefined));
+}
+/**
+ * Expand any `<agent>@all` spec into one pinned spec per version installed on the
+ * source, so `--agent claude@all` replicates THIS machine's exact version set.
+ * `versionsOf` returns the source's installed versions for an agent id. Every
+ * other spec passes through unchanged; the result is de-duplicated in order.
+ * Throws if `@all` names an agent with no installed versions here (nothing to
+ * replicate — a clear misconfig, not a silent no-op).
+ */
+export function expandAllSpecs(specs, versionsOf) {
+    const out = [];
+    for (const spec of specs) {
+        const at = spec.indexOf('@');
+        const label = at >= 0 ? spec.slice(at + 1).trim() : '';
+        if (label !== 'all') {
+            out.push(spec);
+            continue;
+        }
+        const id = agentIdOf(spec);
+        const versions = versionsOf(id);
+        if (versions.length === 0) {
+            throw new Error(`--agent ${spec}: no ${id} versions installed on this machine to replicate.`);
+        }
+        for (const v of versions)
+            out.push(`${id}@${v}`);
+    }
+    return [...new Set(out)];
+}
+/**
+ * Parse `agents view --json` (the all-agents array form) into a map of agent id
+ * -> installed version strings. Tolerant: returns undefined on any parse failure
+ * so a version-pinned spec falls back to id-level presence rather than crashing.
+ */
+export function parseInstalledVersions(stdout) {
+    try {
+        const arr = JSON.parse(stdout);
+        if (!Array.isArray(arr))
+            return undefined;
+        const out = {};
+        for (const a of arr) {
+            if (a && typeof a.agent === 'string' && Array.isArray(a.versions)) {
+                out[a.agent] = a.versions
+                    .map((v) => v?.version)
+                    .filter((v) => typeof v === 'string');
+            }
+        }
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Can we propagate `agent`'s login to a target on `targetPlatform`? False when
  * the agent has no portable file, the source can't provide it (bound / not
@@ -53,21 +123,28 @@ export function diffFleet(desired, probes, ctx) {
             else if (probe.cliVersion !== ctx.targetCliVersion) {
                 rowActions.push({ device: d.device, kind: 'upgrade-cli', detail: `agents-cli ${probe.cliVersion} -> ${ctx.targetCliVersion}` });
             }
-            // agents.
+            // agents. A version-pinned spec (`claude@2.1.170`, or an expanded
+            // `claude@all` member) is present only when that exact version is on the
+            // device; a bare/latest spec diffs at id granularity. So `--agent claude@all`
+            // installs every missing version even when some claude is already there.
             for (const spec of d.agents) {
                 const id = agentIdOf(spec);
-                if (!probe.installedAgents.includes(id)) {
-                    rowActions.push({ device: d.device, kind: 'add-agent', agent: id, detail: `install ${spec}` });
+                const want = pinnedVersion(spec);
+                const present = want !== undefined
+                    ? (probe.installedVersions?.[id]?.includes(want) ?? false)
+                    : probe.installedAgents.includes(id);
+                if (!present) {
+                    rowActions.push({ device: d.device, kind: 'add-agent', agent: id, spec, detail: `install ${spec}` });
                 }
             }
             // config.
             if (d.sync.length > 0) {
                 rowActions.push({ device: d.device, kind: 'sync-config', detail: `sync config (${d.sync.join(', ')})` });
             }
-            // login.
+            // login — per agent id, not per spec: `claude@all` names one id many times,
+            // but login propagates once per agent (its credential is version-shared).
             if (d.login === 'sync') {
-                for (const spec of d.agents) {
-                    const id = agentIdOf(spec);
+                for (const id of [...new Set(d.agents.map(agentIdOf))]) {
                     if (canPushLogin(id, probe.platform, ctx.sourceAuth)) {
                         rowActions.push({ device: d.device, kind: 'push-login', agent: id, detail: `propagate ${id} login` });
                     }
@@ -107,8 +184,9 @@ function osHint(platform) {
 function remoteEnv(platform) {
     return platform === 'windows' ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
 }
-/** Probe one device: reachability + agents-cli version + installed agent ids. */
-export function probeDevice(device) {
+/** Probe one device: reachability + agents-cli version + installed agent ids
+ * (and, when `withVersions`, the installed version strings per agent). */
+export function probeDevice(device, opts) {
     let target;
     try {
         target = sshTargetFor(device);
@@ -133,12 +211,20 @@ export function probeDevice(device) {
             /* agents-cli present but doctor output unparsable — treat as no agents */
         }
     }
+    let installedVersions;
+    if (opts?.withVersions) {
+        const viewCmd = buildRemoteAgentsInvocation(['view', '--json'], undefined, hint, remoteEnv(device.platform));
+        const vres = sshExec(target, viewCmd, { timeoutMs: 30000, multiplex: true });
+        if (vres.code === 0)
+            installedVersions = parseInstalledVersions(vres.stdout);
+    }
     return {
         device: device.name,
         reachable: true,
         platform: device.platform,
         cliVersion: ready.version ?? undefined,
         installedAgents: installed,
+        installedVersions,
     };
 }
 /** Execute one device's planned actions in order. Real SSH — no mocks. */
@@ -165,9 +251,10 @@ export function reconcileDevice(row, device, ctx) {
         steps.push({ kind: cliAction.kind, ok: r.ok, detail: cliAction.detail });
         ok = ok && r.ok;
     }
-    // 2. agents.
+    // 2. agents. Every add-agent action carries the full spec (set in diffFleet);
+    // install it directly rather than re-parsing the human-readable detail string.
     for (const a of row.actions.filter((x) => x.kind === 'add-agent')) {
-        const spec = a.detail.replace(/^install\s+/, '');
+        const spec = a.spec;
         const r = sshAgents(['add', spec, '--yes']);
         steps.push({ kind: 'add-agent', ok: r.code === 0, detail: a.detail });
         ok = ok && r.code === 0;

package/dist/lib/fleet/types.d.ts

@@ -87,6 +87,14 @@ export interface DeviceProbe {
     cliVersion?: string;
     /** Agent ids currently installed on the device. */
     installedAgents: string[];
+    /**
+     * Installed version strings per agent id (e.g. `{ claude: ['2.1.170', '2.1.207'] }`),
+     * parsed from `agents view --json` on the device. Only populated when the plan
+     * involves a version-pinned spec (`claude@2.1.170`, or a `claude@all` expansion)
+     * — a bare `claude`/`claude@latest` roster never pays for the extra probe. When
+     * undefined, version-pinned specs fall back to id-level presence.
+     */
+    installedVersions?: Record<string, string[]>;
     /** Reason string when `reachable` is false or the probe partially failed. */
     note?: string;
 }
@@ -100,6 +108,9 @@ export interface FleetAction {
     kind: FleetActionKind;
     /** Agent id for agent/login actions; undefined for cli/config actions. */
     agent?: string;
+    /** Full agent spec for `add-agent` (e.g. `claude@2.1.170`) so the plan can show
+     * the exact version being installed; equals the id for a bare/latest spec. */
+    spec?: string;
     /** Human, one-line description of the action. */
     detail: string;
 }

package/dist/lib/fs-walk.d.ts

@@ -1,3 +1,16 @@
+/** A file surfaced by the walk, carrying the mtime+size from the walk's own stat. */
+export interface WalkedFile {
+    path: string;
+    mtimeMs: number;
+    size: number;
+}
+/**
+ * Walk a directory recursively for files with a given extension, newest first,
+ * keeping each match's mtime and size from the walk's own stat. Callers that
+ * then compare against the scan ledger reuse these instead of re-stat'ing every
+ * path — eliminating a second stat per file on the Codex/Droid/routine scans.
+ */
+export declare function walkForFilesWithStat(dir: string, ext: string, limit: number): WalkedFile[];
 /** Walk a directory recursively for files with a given extension, newest first. */
 export declare function walkForFiles(dir: string, ext: string, limit: number): string[];
 /**

package/dist/lib/fs-walk.js

@@ -36,20 +36,29 @@ function walkEntries(dir, ext, onFile) {
             else if (entry.name.endsWith(ext)) {
                 const stat = safeStatSync(full);
                 if (stat)
-                    onFile(full, stat.mtimeMs);
+                    onFile(full, stat.mtimeMs, stat.size);
             }
         }
     }
     walk(dir, 0);
 }
-/** Walk a directory recursively for files with a given extension, newest first. */
-export function walkForFiles(dir, ext, limit) {
+/**
+ * Walk a directory recursively for files with a given extension, newest first,
+ * keeping each match's mtime and size from the walk's own stat. Callers that
+ * then compare against the scan ledger reuse these instead of re-stat'ing every
+ * path — eliminating a second stat per file on the Codex/Droid/routine scans.
+ */
+export function walkForFilesWithStat(dir, ext, limit) {
     const results = [];
-    walkEntries(dir, ext, (filePath, mtimeMs) => {
-        results.push({ path: filePath, mtime: mtimeMs });
+    walkEntries(dir, ext, (filePath, mtimeMs, size) => {
+        results.push({ path: filePath, mtimeMs, size });
     });
-    results.sort((a, b) => b.mtime - a.mtime);
-    return results.slice(0, limit).map(r => r.path);
+    results.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return results.slice(0, limit);
+}
+/** Walk a directory recursively for files with a given extension, newest first. */
+export function walkForFiles(dir, ext, limit) {
+    return walkForFilesWithStat(dir, ext, limit).map(r => r.path);
 }
 /**
  * Return the newest mtime (ms) among files with the given extension, or null

package/dist/lib/hooks.d.ts

@@ -139,6 +139,7 @@ export declare function listCentralHooks(): HookEntry[];
 export declare function parseHookManifest(opts?: {
     warn?: boolean;
 }): Record<string, ManifestHook>;
+export declare function selectHookManifest(manifest: Record<string, ManifestHook>, selected: string[]): Record<string, ManifestHook>;
 /**
  * Hook script files present on disk that no manifest entry declares — "dead"
  * hooks. The registrar only wires manifest-declared hooks into an agent's