@phnx-labs/agents-cli 1.20.51 → 1.20.52

package/dist/lib/events.js

@@ -1,8 +1,8 @@
 /**
  * Centralized event logging for agents-cli.
  *
- * Structured JSONL logs at ~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl
- * with automatic daily rotation and rich metadata for debugging/auditing.
+ * Structured JSONL audit log at ~/.agents/events.jsonl with lossless numbered
+ * gzip rotation at 10 MB and rich metadata for debugging/auditing.
  *
  * Features:
  * - Rich metadata: hostname, platform, arch, pid, timezone
@@ -15,30 +15,26 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { createHash } from 'node:crypto';
+import { gzipSync, gunzipSync } from 'node:zlib';
 import { parseSshConnection } from './session/provenance.js';
-import { getLogsDir } from './state.js';
+import { ensureLockTarget, withFileLock } from './fs-atomic.js';
+import { getUserAgentsDir } from './state.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
-// Logs live under the cache bucket — they're regenerable telemetry. Route
-// through state's canonical home anchor (HOME override → os.homedir()) rather
-// than a bare os.homedir(): on Windows os.homedir() reads USERPROFILE and
-// ignores a HOME override, so a test (or any caller) that redirects HOME would
-// have its events silently written to the real profile instead. state.getLogsDir()
-// honors the HOME override on every platform while falling back to os.homedir()
-// (== USERPROFILE on Windows) in production where HOME is unset.
-//
-// Resolved lazily + memoized: importing this module must NOT call getLogsDir()
-// at eval time. events.ts is pulled in transitively (skills/versions/exec/
-// runner), and several tests mock './state.js' with partial factories that omit
-// getLogsDir — an eager call would crash those on import. Deferring to first use
-// keeps a bare import side-effect-free while staying a one-time resolution.
-let _logsDir;
-function logsDir() {
-    return (_logsDir ??= getLogsDir());
+// Resolved lazily: events.ts is imported transitively by most CLI surfaces, and
+// import itself must stay side-effect free. Tests may override the exact path.
+let _eventsPath;
+function eventsPath() {
+    return (_eventsPath ??= path.join(getUserAgentsDir(), 'events.jsonl'));
+}
+function eventsDir() {
+    return path.dirname(eventsPath());
 }
 /** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 7;
 /** Default max length for truncated strings. */
 const DEFAULT_TRUNCATE_LENGTH = 500;
+/** Gzip rotation threshold in bytes (10 MB). */
+const GZIP_ROTATION_BYTES = 10 * 1024 * 1024;
 /** Environment variable to disable event logging. */
 const DISABLE_ENV_VAR = 'AGENTS_DISABLE_EVENT_LOG';
 /** Check if audit logging is disabled via environment variable. */
@@ -50,6 +46,26 @@ function isDisabled() {
 const DIR_MODE = 0o700;
 /** File permissions (owner read/write only). */
 const FILE_MODE = 0o600;
+const AUDIT_EVENTS = new Set([
+    'command.start', 'command.end',
+    'secrets.get', 'secrets.set', 'secrets.delete', 'secrets.rename',
+    'teams.create', 'teams.add', 'teams.start', 'teams.complete', 'teams.disband',
+    'cloud.dispatch', 'cloud.complete', 'cloud.cancel', 'cloud.message',
+    'version.install', 'version.switch', 'version.remove',
+    'skill.install', 'skill.remove',
+    'mcp.add', 'mcp.remove', 'mcp.register',
+    'rotation.resolved',
+    'session.start', 'session.end',
+]);
+export function levelFor(event) {
+    if (event === 'warn')
+        return 'warn';
+    if (event === 'debug')
+        return 'debug';
+    if (AUDIT_EVENTS.has(event))
+        return 'audit';
+    return 'info';
+}
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function getTimezoneOffset() {
     const offset = new Date().getTimezoneOffset();
@@ -66,20 +82,14 @@ function getTimezoneName() {
         return 'Unknown';
     }
 }
-function getLogFilePath(date = new Date()) {
-    const yyyy = date.getFullYear();
-    const mm = String(date.getMonth() + 1).padStart(2, '0');
-    const dd = String(date.getDate()).padStart(2, '0');
-    return path.join(logsDir(), `events-${yyyy}-${mm}-${dd}.jsonl`);
-}
 function ensureLogsDir() {
-    if (!fs.existsSync(logsDir())) {
-        fs.mkdirSync(logsDir(), { recursive: true, mode: DIR_MODE });
+    if (!fs.existsSync(eventsDir())) {
+        fs.mkdirSync(eventsDir(), { recursive: true, mode: DIR_MODE });
     }
     else {
         // Ensure permissions are correct on existing dir
         try {
-            fs.chmodSync(logsDir(), DIR_MODE);
+            fs.chmodSync(eventsDir(), DIR_MODE);
         }
         catch {
             // May fail if not owner
@@ -101,6 +111,16 @@ export function redactPrompt(prompt) {
 }
 const TOKEN_LIKE = /(sk_(?:live|test)_|pk_(?:live|test)_|ghp_|gho_|ghu_|ghs_|xox[bpars]-|AKIA|ASIA|AIza|Bearer\s+|eyJ[A-Za-z0-9_-]+\.)/i;
 const SECRET_PATH = /\/(secrets|credentials|\.env|user\.yaml)\b/i;
+const SENSITIVE_ARG_NAME = /password|secret|token|key|api[-_]?key|auth/i;
+const SENSITIVE_PAYLOAD_KEY = /password|secret|token|api[-_]?key|auth/i;
+const RESERVED_META_KEYS = new Set([
+    'ts', 'tz', 'tzName', 'hostname', 'platform', 'arch', 'pid', 'ppid',
+    'event', 'level', 'caller', 'session', 'osUser', 'transport', 'sshClientIp',
+]);
+function promptMarker(value) {
+    const { prompt_length, prompt_sha256 } = redactPrompt(value);
+    return `[REDACTED prompt length=${prompt_length} sha256=${prompt_sha256}]`;
+}
 /**
  * Mask argv entries that look like tokens or secret paths. Preserves structure
  * for debugging but drops the sensitive substring.
@@ -108,13 +128,59 @@ const SECRET_PATH = /\/(secrets|credentials|\.env|user\.yaml)\b/i;
 export function redactArgs(args) {
     if (!args)
         return undefined;
-    return args.map(a => {
-        if (typeof a !== 'string')
-            return a;
-        if (TOKEN_LIKE.test(a) || SECRET_PATH.test(a))
-            return '[REDACTED]';
-        return a;
-    });
+    const result = [];
+    let redactNext = false;
+    let promptNext = false;
+    for (const arg of args) {
+        if (redactNext) {
+            if (arg.startsWith('-')) {
+                redactNext = false;
+            }
+            else {
+                result.push('[REDACTED]');
+                redactNext = false;
+                continue;
+            }
+        }
+        if (promptNext) {
+            if (arg.startsWith('-')) {
+                promptNext = false;
+            }
+            else {
+                result.push(arg.length > 200 ? promptMarker(arg) :
+                    TOKEN_LIKE.test(arg) || SECRET_PATH.test(arg) ? '[REDACTED]' : arg);
+                promptNext = false;
+                continue;
+            }
+        }
+        const equals = arg.indexOf('=');
+        const flag = equals >= 0 ? arg.slice(0, equals) : arg;
+        const value = equals >= 0 ? arg.slice(equals + 1) : undefined;
+        if (flag.startsWith('-') && SENSITIVE_ARG_NAME.test(flag)) {
+            result.push(value === undefined ? flag : `${flag}=[REDACTED]`);
+            redactNext = value === undefined;
+            continue;
+        }
+        if (flag === '--body' || flag === '--value') {
+            result.push(value === undefined ? flag : `${flag}=[REDACTED]`);
+            redactNext = value === undefined;
+            continue;
+        }
+        if (flag === '--prompt') {
+            if (value === undefined) {
+                result.push(flag);
+                promptNext = true;
+            }
+            else {
+                const safe = value.length > 200 ? promptMarker(value) :
+                    TOKEN_LIKE.test(value) || SECRET_PATH.test(value) ? '[REDACTED]' : value;
+                result.push(`${flag}=${safe}`);
+            }
+            continue;
+        }
+        result.push(TOKEN_LIKE.test(arg) || SECRET_PATH.test(arg) ? '[REDACTED]' : arg);
+    }
+    return result;
 }
 // ─── Truncation ───────────────────────────────────────────────────────────────
 /**
@@ -131,22 +197,65 @@ export function truncate(str, maxLength = DEFAULT_TRUNCATE_LENGTH) {
 /**
  * Truncate all string values in a payload object.
  */
-function truncatePayload(payload, maxLength = DEFAULT_TRUNCATE_LENGTH) {
+function sanitizeNested(value, key, maxLength) {
+    if (SENSITIVE_PAYLOAD_KEY.test(key))
+        return '[REDACTED]';
+    if (typeof value === 'string') {
+        if (TOKEN_LIKE.test(value) || SECRET_PATH.test(value))
+            return '[REDACTED]';
+        return truncate(value, maxLength);
+    }
+    if (Array.isArray(value)) {
+        return value.slice(0, 10).map((item) => sanitizeNested(item, '', maxLength));
+    }
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [nestedKey, nestedValue] of Object.entries(value)) {
+            result[nestedKey] = sanitizeNested(nestedValue, nestedKey, maxLength);
+        }
+        return result;
+    }
+    return value;
+}
+function sanitizePayload(payload, maxLength = DEFAULT_TRUNCATE_LENGTH) {
     const result = {};
     for (const [key, value] of Object.entries(payload)) {
-        if (typeof value === 'string') {
-            result[key] = truncate(value, maxLength);
-        }
-        else if (Array.isArray(value)) {
-            // Truncate array to first 10 items, truncate each string item
-            result[key] = value.slice(0, 10).map(v => typeof v === 'string' ? truncate(v, maxLength) : v);
+        if (RESERVED_META_KEYS.has(key))
+            continue;
+        if (key === 'args' && Array.isArray(value)) {
+            result.args = redactArgs(value.filter((item) => typeof item === 'string'));
+            continue;
         }
-        else {
-            result[key] = value;
+        if (key.toLowerCase() === 'prompt' && typeof value === 'string') {
+            Object.assign(result, redactPrompt(value));
+            continue;
         }
+        result[key] = sanitizeNested(value, key, maxLength);
     }
     return result;
 }
+const TERMINAL_CALLERS = {
+    cc: 'claude', cl: 'claude',
+    cx: 'codex',
+    gx: 'gemini', gm: 'gemini',
+    cr: 'cursor',
+    oc: 'opencode',
+    sh: 'shell',
+    ag: 'antigravity',
+    gk: 'grok',
+};
+/** Identify the environment that invoked agents-cli, not the source callsite. */
+export function detectCaller(env = process.env, stdoutIsTTY = Boolean(process.stdout.isTTY)) {
+    const session = env.AGENT_SESSION_ID?.slice(0, 8) || undefined;
+    if (env.CLAUDECODE === '1')
+        return { kind: 'claude-code', ...(session ? { session } : {}) };
+    const terminalId = env.AGENT_TERMINAL_ID;
+    if (terminalId) {
+        const prefix = terminalId.split('-')[0].toLowerCase();
+        return { kind: TERMINAL_CALLERS[prefix] ?? 'agent', ...(session ? { session } : {}) };
+    }
+    return { kind: stdoutIsTTY ? 'terminal' : 'script' };
+}
 /**
  * Who is running this process and from where. Derived once per process from the
  * OS user and $SSH_CONNECTION (via the same parser the sessions layer uses), then
@@ -173,7 +282,7 @@ function auditOrigin() {
 }
 // ─── Core API ─────────────────────────────────────────────────────────────────
 /**
- * Emit a structured event to the daily log file.
+ * Emit a structured event to the append-only audit log.
  *
  * @param event - The event type
  * @param payload - Event-specific data (agent, version, cwd, etc.)
@@ -183,7 +292,10 @@ export function emit(event, payload = {}) {
         return;
     try {
         ensureLogsDir();
+        const caller = detectCaller();
+        const safePayload = sanitizePayload(payload);
         const record = {
+            ...safePayload,
             ts: new Date().toISOString(),
             tz: getTimezoneOffset(),
             tzName: getTimezoneName(),
@@ -193,26 +305,28 @@ export function emit(event, payload = {}) {
             pid: process.pid,
             ppid: process.ppid,
             event,
+            level: levelFor(event),
+            caller: caller.kind,
+            ...(caller.session ? { session: caller.session } : {}),
             ...auditOrigin(),
-            ...truncatePayload(payload),
         };
         const line = JSON.stringify(record) + '\n';
-        const logPath = getLogFilePath();
+        const logPath = eventsPath();
         const isNew = !fs.existsSync(logPath);
-        fs.appendFileSync(logPath, line, { mode: FILE_MODE });
-        // appendFileSync's mode only applies when it CREATES the file, so we chmod
-        // to guarantee 0600 — but only on first write to a given path this process.
-        // command.start/end fire on every invocation; chmod-per-append would double
-        // the syscalls on the hot path for no gain (perms don't drift mid-run).
-        if (isNew || logPath !== _chmoddedPath) {
-            _chmoddedPath = logPath;
-            try {
-                fs.chmodSync(logPath, FILE_MODE);
-            }
-            catch {
-                // May fail if not owner
+        ensureLockTarget(logPath, '', DIR_MODE);
+        withFileLock(logPath, () => {
+            fs.appendFileSync(logPath, line, { mode: FILE_MODE });
+            if (isNew || logPath !== _chmoddedPath) {
+                _chmoddedPath = logPath;
+                try {
+                    fs.chmodSync(logPath, FILE_MODE);
+                }
+                catch {
+                    // May fail if not owner
+                }
             }
-        }
+            maybeGzipRotateLocked(logPath);
+        });
     }
     catch {
         // Silent failure - logging should never break the CLI
@@ -401,29 +515,54 @@ export function emitError(err, payload = {}) {
         errorStack: truncate(error.stack, 1000),
     });
 }
+// ─── Gzip rotation ──────────────────────────────────────────────────────────
+/** Rotate the active file while its append lock is held. */
+function maybeGzipRotateLocked(logPath) {
+    const stat = fs.statSync(logPath);
+    if (stat.size < GZIP_ROTATION_BYTES)
+        return;
+    const raw = fs.readFileSync(logPath);
+    const tmpArchive = path.join(eventsDir(), `.events.1.jsonl.gz.${process.pid}.tmp`);
+    fs.writeFileSync(tmpArchive, gzipSync(raw), { mode: FILE_MODE });
+    try {
+        const archives = fs.readdirSync(eventsDir())
+            .map((file) => ({ file, match: file.match(/^events\.(\d+)\.jsonl\.gz$/) }))
+            .filter((entry) => entry.match !== null)
+            .map((entry) => ({ file: entry.file, number: Number(entry.match[1]) }))
+            .sort((a, b) => b.number - a.number);
+        for (const archive of archives) {
+            fs.renameSync(path.join(eventsDir(), archive.file), path.join(eventsDir(), `events.${archive.number + 1}.jsonl.gz`));
+        }
+        fs.renameSync(tmpArchive, path.join(eventsDir(), 'events.1.jsonl.gz'));
+        fs.truncateSync(logPath, 0);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpArchive);
+        }
+        catch { /* best-effort cleanup */ }
+        throw err;
+    }
+}
 // ─── Rotation ─────────────────────────────────────────────────────────────────
 /**
  * Remove log files older than the retention period.
- * Called lazily on emit or explicitly via CLI.
+ * Removes numbered gzip archives whose filesystem mtime exceeds retention.
  *
  * @param retentionDays - Number of days to keep (default 7, from DEFAULT_RETENTION_DAYS)
  * @returns Number of files removed
  */
 export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
     try {
-        if (!fs.existsSync(logsDir()))
+        if (!fs.existsSync(eventsDir()))
             return 0;
         const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
-        const files = fs.readdirSync(logsDir()).filter(f => f.startsWith('events-') && f.endsWith('.jsonl'));
+        const files = fs.readdirSync(eventsDir()).filter(f => /^events\.\d+\.jsonl\.gz$/.test(f));
         let removed = 0;
         for (const file of files) {
-            const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
-            if (!match)
-                continue;
-            const [, yyyy, mm, dd] = match;
-            const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
-            if (fileDate.getTime() < cutoff) {
-                fs.unlinkSync(path.join(logsDir(), file));
+            const filePath = path.join(eventsDir(), file);
+            if (fs.statSync(filePath).mtimeMs < cutoff) {
+                fs.unlinkSync(filePath);
                 removed++;
             }
         }
@@ -453,42 +592,40 @@ export function maybeRotate() {
  * @returns Array of event records
  */
 export function query(options) {
-    const { startDate, endDate = new Date(), eventTypes, agent, command, module, limit } = options;
+    const { startDate, endDate = new Date(), eventTypes, level, agent, caller, command, module, limit } = options;
     const results = [];
-    if (!fs.existsSync(logsDir()))
+    if (!fs.existsSync(eventsDir()))
         return results;
-    const files = fs.readdirSync(logsDir())
-        .filter(f => f.startsWith('events-') && f.endsWith('.jsonl'))
-        .sort()
-        .reverse();
-    // Coarse file skip works on whole days, so floor the bounds to midnight —
-    // otherwise a sub-day window (`--since 2h` at 15:00 → startDate 13:00) would
-    // drop *today's* file, whose date stamps to 00:00. Precise filtering below is
-    // per-record on `ts`.
-    const startDay = startDate
-        ? new Date(startDate.getFullYear(), startDate.getMonth(), startDate.getDate())
-        : undefined;
-    const endDay = endDate
-        ? new Date(endDate.getFullYear(), endDate.getMonth(), endDate.getDate())
-        : undefined;
+    const files = [];
+    if (fs.existsSync(eventsPath()))
+        files.push({ path: eventsPath(), gzip: false });
+    const archives = fs.readdirSync(eventsDir())
+        .map((file) => ({ file, match: file.match(/^events\.(\d+)\.jsonl\.gz$/) }))
+        .filter((entry) => entry.match !== null)
+        .map((entry) => ({ file: entry.file, number: Number(entry.match[1]) }))
+        .sort((a, b) => a.number - b.number);
+    for (const archive of archives) {
+        files.push({ path: path.join(eventsDir(), archive.file), gzip: true });
+    }
     const startMs = startDate?.getTime();
     const endMs = endDate?.getTime();
     for (const file of files) {
-        const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
-        if (!match)
-            continue;
-        const [, yyyy, mm, dd] = match;
-        const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
-        if (startDay && fileDate < startDay)
-            continue;
-        if (endDay && fileDate > endDay)
-            continue;
-        const content = fs.readFileSync(path.join(logsDir(), file), 'utf-8');
+        let content;
+        if (file.gzip) {
+            try {
+                content = gunzipSync(fs.readFileSync(file.path)).toString('utf-8');
+            }
+            catch {
+                continue;
+            }
+        }
+        else {
+            content = fs.readFileSync(file.path, 'utf-8');
+        }
         const lines = content.trim().split('\n').filter(Boolean);
         for (const line of lines.reverse()) {
             try {
                 const record = JSON.parse(line);
-                // Precise per-record window — the file skip above is day-granular only.
                 const recMs = Date.parse(record.ts);
                 if (startMs !== undefined && !isNaN(recMs) && recMs < startMs)
                     continue;
@@ -496,11 +633,12 @@ export function query(options) {
                     continue;
                 if (eventTypes && !eventTypes.includes(record.event))
                     continue;
+                if (level && (record.level ?? levelFor(record.event)) !== level)
+                    continue;
                 if (agent && record.agent !== agent)
                     continue;
-                // `--command` matches by path prefix on a word boundary, so a coarse
-                // "teams" catches "teams create"/"teams remove" while an exact
-                // "teams create" stays exact.
+                if (caller && record.caller !== caller)
+                    continue;
                 if (command && record.command !== command &&
                     !(typeof record.command === 'string' && record.command.startsWith(command + ' ')))
                     continue;
@@ -543,7 +681,56 @@ export function getTimingStats(label, options = {}) {
         p95Ms: durations[Math.floor(durations.length * 0.95)],
     };
 }
+export function stats(options = {}) {
+    const days = options.days ?? 7;
+    const startDate = new Date();
+    startDate.setDate(startDate.getDate() - days);
+    const records = query({ startDate, limit: 100_000 });
+    const byLevel = {};
+    const byEvent = {};
+    const byModule = {};
+    const byUser = {};
+    for (const r of records) {
+        const lvl = r.level ?? levelFor(r.event);
+        byLevel[lvl] = (byLevel[lvl] ?? 0) + 1;
+        byEvent[r.event] = (byEvent[r.event] ?? 0) + 1;
+        if (r.module)
+            byModule[r.module] = (byModule[r.module] ?? 0) + 1;
+        const user = `${r.osUser ?? '?'}@${r.hostname}`;
+        byUser[user] = (byUser[user] ?? 0) + 1;
+    }
+    let fileCount = 0;
+    let totalBytes = 0;
+    try {
+        if (fs.existsSync(eventsDir())) {
+            const files = fs.readdirSync(eventsDir()).filter(f => f === 'events.jsonl' || /^events\.\d+\.jsonl\.gz$/.test(f));
+            fileCount = files.length;
+            for (const f of files) {
+                try {
+                    totalBytes += fs.statSync(path.join(eventsDir(), f)).size;
+                }
+                catch { /* skip */ }
+            }
+        }
+    }
+    catch { /* skip */ }
+    return {
+        totalEvents: records.length,
+        byLevel,
+        byEvent,
+        byModule,
+        byUser,
+        fileCount,
+        totalBytes,
+    };
+}
 // ─── Exports ──────────────────────────────────────────────────────────────────
 export function getLogsPath() {
-    return logsDir();
+    return eventsPath();
+}
+export function _resetForTest(overrideEventsPath) {
+    _eventsPath = overrideEventsPath;
+    _origin = undefined;
+    _chmoddedPath = undefined;
+    lastRotationCheck = 0;
 }

package/dist/lib/exec.js

@@ -269,6 +269,7 @@ export function buildExecEnv(options) {
     if (options.sessionId && isValidMailboxId(options.sessionId)) {
         result.AGENTS_MAILBOX_DIR = mailboxDir(options.sessionId);
     }
+    result.AGENTS_RUNTIME = resolveInteractive(options) ? 'terminal' : 'headless';
     // Export the run's durable name (companion to AGENT_SESSION_ID) so a
     // SessionStart hook / the agent can associate its transcript with the handle
     // the user gave the run. Only set when --name was passed.

package/dist/lib/feed.d.ts

@@ -0,0 +1,56 @@
+export interface BlockOption {
+    label: string;
+    description?: string;
+}
+export interface BlockQuestion {
+    text: string;
+    header?: string;
+    options?: BlockOption[];
+    multiSelect?: boolean;
+}
+export interface OpenBlock {
+    blockId: string;
+    sessionId: string;
+    mailboxId: string;
+    host: string;
+    runtime: string;
+    ts: string;
+    questions: BlockQuestion[];
+    ticket?: string;
+    pr?: string;
+}
+/**
+ * Stable block id for a session. One block per session -- a new question
+ * replaces the previous one (the agent can only ask one question at a time).
+ */
+export declare function blockIdForSession(sessionId: string): string;
+/** Atomic write a block record to the feed store. */
+export declare function publishBlock(block: OpenBlock, root?: string): void;
+/** Read all block records. Returns them sorted by stable block filename. */
+export declare function listBlocks(root?: string): OpenBlock[];
+/** Remove a block record. Returns true if the file was deleted. */
+export declare function removeBlock(blockId: string, root?: string): boolean;
+/**
+ * The feed-publish PreToolUse hook script (Python, mirroring 09-mailbox-inject.py).
+ * Embedded so it ships with the compiled CLI and can be installed to the
+ * CLI-writable user hooks dir without a separate file in the npm tarball.
+ */
+export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"PreToolUse hook: publish an open-block record when the agent calls\nAskUserQuestion, so `agents feed` can aggregate pending decisions.\n\nOutbound counterpart to the inbound mailbox-inject hook. Fires only on\nAskUserQuestion (matcher-gated in agents.yaml). Writes one block per session\nto ~/.agents/.history/feed/. A new question replaces the previous block.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\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.\n    if payload.get(\"agent_type\"):\n        return\n\n    tool_input = payload.get(\"tool_input\", {})\n    questions = tool_input.get(\"questions\", [])\n    if not questions:\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    normalized_questions = []\n    for q in questions:\n        if not isinstance(q, dict):\n            continue\n        question = {\n            \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n            \"header\": q.get(\"header\"),\n            \"multiSelect\": q.get(\"multiSelect\", False),\n        }\n        raw_opts = q.get(\"options\", [])\n        if raw_opts:\n            question[\"options\"] = [\n                {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                for o in raw_opts\n                if isinstance(o, dict)\n            ]\n        normalized_questions.append(question)\n    if not normalized_questions:\n        return\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": datetime.now(timezone.utc).isoformat(),\n        \"questions\": normalized_questions,\n    }\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    os.makedirs(feed_dir, exist_ok=True)\n\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.rename(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
+/** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
+export declare const FEED_PUBLISH_HOOK_MANIFEST: {
+    name: string;
+    events: string[];
+    matcher: string;
+    script: string;
+    timeout: number;
+};
+/**
+ * Install the feed-publish hook script into the user hooks dir and add its
+ * manifest entry to the user agents.yaml. The system repo is an auto-pulled,
+ * read-only mirror, so runtime-managed hooks must never write there.
+ * Idempotent -- skips if the script is already present and up to date.
+ */
+export declare function ensureFeedPublishHook(userAgentsDir?: string): {
+    installed: boolean;
+    error?: string;
+};