@phnx-labs/agents-cli 1.20.90 → 1.20.92

package/dist/lib/events.d.ts

@@ -20,6 +20,14 @@ export interface EventMeta {
     tz: string;
     tzName: string;
     hostname: string;
+    /**
+     * Normalized, joinable device id (`machine-id.ts::machineId()`) — the same key
+     * `agents devices`/session-sync use, so an event can be matched to a device.
+     * `hostname` is the raw `os.hostname()`; `machineId` is `zion` for `Zion.local`.
+     * Optional on the type so legacy records (pre-provenance-floor) and the activity
+     * stream still parse; `emit()` always stamps it on the operational log.
+     */
+    machineId?: string;
     platform: NodeJS.Platform;
     arch: string;
     pid: number;
@@ -40,6 +48,10 @@ export interface EventPayload {
     agent?: string;
     version?: string;
     sessionId?: string;
+    /** Spawn-time join key (AGENT_LAUNCH_ID) mapping this action to its launch. */
+    launchId?: string;
+    /** The session that spawned this one (AGENTS_PARENT_SESSION_ID) — lineage edge. */
+    parentSessionId?: string;
     cwd?: string;
     /** Top-level command group, e.g. 'teams', 'secrets' — the audit filter key. */
     module?: string;

package/dist/lib/events.js

@@ -20,6 +20,28 @@ import { parseSshConnection } from './session/provenance.js';
 import { ensureLockTarget, withFileLock } from './fs-atomic.js';
 import { getUserAgentsDir } from './state.js';
 import { resolveActor } from './actor.js';
+import { machineId } from './machine-id.js';
+/** Lazy perf warehouse write — avoids a hard cycle at module load. */
+function recordPerfTiming(payload) {
+    try {
+        // Dynamic import keeps events.ts free of a load-time dependency on perf/db.
+        void import('./perf/spool.js').then(({ recordSample }) => {
+            recordSample({
+                kind: 'perf.timing',
+                label: payload.label,
+                durationMs: payload.durationMs,
+                status: payload.status,
+                agent: payload.agent,
+                agentVersion: payload.version,
+                sessionId: payload.sessionId,
+                cwd: payload.cwd,
+            });
+        }).catch(() => { });
+    }
+    catch {
+        // fail soft
+    }
+}
 // ─── Constants ────────────────────────────────────────────────────────────────
 // 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.
@@ -118,7 +140,7 @@ 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',
+    'ts', 'tz', 'tzName', 'hostname', 'machineId', 'platform', 'arch', 'pid', 'ppid',
     'event', 'level', 'caller', 'session', 'osUser', 'transport', 'sshClientIp',
     'actor', 'kind',
 ]);
@@ -288,6 +310,24 @@ function auditOrigin() {
     };
     return _origin;
 }
+/** This machine's normalized device id, resolved once — it can't change mid-process. */
+let _machineId;
+function cachedMachineId() {
+    return (_machineId ??= machineId());
+}
+function resolveProvenance(env = process.env) {
+    const p = {};
+    const sessionId = env.AGENT_SESSION_ID || env.AGENTS_SESSION_ID;
+    if (sessionId)
+        p.sessionId = sessionId;
+    if (env.AGENTS_AGENT_NAME)
+        p.agent = env.AGENTS_AGENT_NAME;
+    if (env.AGENT_LAUNCH_ID)
+        p.launchId = env.AGENT_LAUNCH_ID;
+    if (env.AGENTS_PARENT_SESSION_ID)
+        p.parentSessionId = env.AGENTS_PARENT_SESSION_ID;
+    return p;
+}
 // ─── Core API ─────────────────────────────────────────────────────────────────
 /**
  * Emit a structured event to the append-only audit log.
@@ -303,11 +343,14 @@ export function emit(event, payload = {}) {
         const caller = detectCaller();
         const safePayload = sanitizePayload(payload);
         const record = {
+            // Provenance floor first: env-sourced defaults an explicit payload overrides.
+            ...resolveProvenance(),
             ...safePayload,
             ts: new Date().toISOString(),
             tz: getTimezoneOffset(),
             tzName: getTimezoneName(),
             hostname: os.hostname(),
+            machineId: cachedMachineId(),
             platform: os.platform(),
             arch: os.arch(),
             pid: process.pid,
@@ -375,22 +418,42 @@ export function time(label, fn, payload = {}) {
     const start = Date.now();
     try {
         const result = fn();
+        const durationMs = Date.now() - start;
         emit('perf.timing', {
             ...payload,
             label,
-            durationMs: Date.now() - start,
+            durationMs,
             status: 'success',
         });
+        recordPerfTiming({
+            label,
+            durationMs,
+            status: 'success',
+            agent: payload.agent,
+            version: payload.version,
+            sessionId: payload.sessionId,
+            cwd: payload.cwd,
+        });
         return result;
     }
     catch (err) {
+        const durationMs = Date.now() - start;
         emit('perf.timing', {
             ...payload,
             label,
-            durationMs: Date.now() - start,
+            durationMs,
             status: 'error',
             error: err instanceof Error ? err.message : String(err),
         });
+        recordPerfTiming({
+            label,
+            durationMs,
+            status: 'error',
+            agent: payload.agent,
+            version: payload.version,
+            sessionId: payload.sessionId,
+            cwd: payload.cwd,
+        });
         throw err;
     }
 }
@@ -405,22 +468,42 @@ export async function timeAsync(label, fn, payload = {}) {
     const start = Date.now();
     try {
         const result = await fn();
+        const durationMs = Date.now() - start;
         emit('perf.timing', {
             ...payload,
             label,
-            durationMs: Date.now() - start,
+            durationMs,
             status: 'success',
         });
+        recordPerfTiming({
+            label,
+            durationMs,
+            status: 'success',
+            agent: payload.agent,
+            version: payload.version,
+            sessionId: payload.sessionId,
+            cwd: payload.cwd,
+        });
         return result;
     }
     catch (err) {
+        const durationMs = Date.now() - start;
         emit('perf.timing', {
             ...payload,
             label,
-            durationMs: Date.now() - start,
+            durationMs,
             status: 'error',
             error: err instanceof Error ? err.message : String(err),
         });
+        recordPerfTiming({
+            label,
+            durationMs,
+            status: 'error',
+            agent: payload.agent,
+            version: payload.version,
+            sessionId: payload.sessionId,
+            cwd: payload.cwd,
+        });
         throw err;
     }
 }
@@ -449,13 +532,22 @@ export function createTimer(label, payload = {}) {
         },
         end(endPayload = {}) {
             const durationMs = Date.now() - start;
+            const merged = { ...payload, ...endPayload };
             emit('perf.timing', {
-                ...payload,
-                ...endPayload,
+                ...merged,
                 label,
                 durationMs,
                 phases: marks,
             });
+            recordPerfTiming({
+                label,
+                durationMs,
+                status: typeof merged.status === 'string' ? merged.status : undefined,
+                agent: merged.agent,
+                version: merged.version,
+                sessionId: merged.sessionId,
+                cwd: merged.cwd,
+            });
         },
     };
 }
@@ -472,22 +564,42 @@ export function withTiming(label, fn, basePayload = {}) {
         const start = Date.now();
         try {
             const result = await fn(...args);
+            const durationMs = Date.now() - start;
             emit('perf.timing', {
                 ...basePayload,
                 label,
-                durationMs: Date.now() - start,
+                durationMs,
                 status: 'success',
             });
+            recordPerfTiming({
+                label,
+                durationMs,
+                status: 'success',
+                agent: basePayload.agent,
+                version: basePayload.version,
+                sessionId: basePayload.sessionId,
+                cwd: basePayload.cwd,
+            });
             return result;
         }
         catch (err) {
+            const durationMs = Date.now() - start;
             emit('perf.timing', {
                 ...basePayload,
                 label,
-                durationMs: Date.now() - start,
+                durationMs,
                 status: 'error',
                 error: err instanceof Error ? err.message : String(err),
             });
+            recordPerfTiming({
+                label,
+                durationMs,
+                status: 'error',
+                agent: basePayload.agent,
+                version: basePayload.version,
+                sessionId: basePayload.sessionId,
+                cwd: basePayload.cwd,
+            });
             throw err;
         }
     };
@@ -756,6 +868,7 @@ export function getLogsPath() {
 export function _resetForTest(overrideEventsPath) {
     _eventsPath = overrideEventsPath;
     _origin = undefined;
+    _machineId = undefined;
     _chmoddedPath = undefined;
     lastRotationCheck = 0;
 }

package/dist/lib/exec.js

@@ -373,6 +373,16 @@ export function buildExecEnv(options) {
         result.AGENT_SESSION_ID = options.sessionId;
         result.AGENTS_SESSION_ID = options.sessionId;
     }
+    // Lineage edge: the child's parent is THIS process's session (the spawner), so a
+    // sub-agent's events carry a walkable edge back to who spawned it. The event floor
+    // (events.ts::resolveProvenance) reads AGENTS_PARENT_SESSION_ID and stamps it on
+    // every event the child emits. `options.sessionId` is the CHILD's id, so read the
+    // spawner from the live env; guard a same-session resume from naming itself parent.
+    // Local-spawn scope here; forwarding it across the `--host` SSH hop is Phase 4.
+    const spawnerSessionId = process.env.AGENTS_SESSION_ID || process.env.AGENT_SESSION_ID;
+    if (spawnerSessionId && spawnerSessionId !== options.sessionId) {
+        result.AGENTS_PARENT_SESSION_ID = spawnerSessionId;
+    }
     result.AGENTS_RUNTIME = resolveInteractive(options) ? 'terminal' : 'headless';
     // So activity / feed posts stamp the right harness without re-detecting.
     if (options.agent) {

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

@@ -28,7 +28,54 @@ export interface FeedBroadcastContext {
     session?: string;
     /** URLs attached to the post — the PR, the ticket, a shared plan. */
     links?: string[];
+    /** Block-only: the block's stable id. Absent on a status post. */
+    blockId?: string;
+    /** Block-only: `approval` (has a safe default) or `decision` (needs a human). */
+    class?: string;
+    /** Block-only: cost-of-delay tag used by the urgency filter. */
+    cost?: string;
+    /** Block-only: the literal `agents focus <id>` command that unblocks it. */
+    focus?: string;
 }
+/**
+ * Map an open block onto the broadcast context, so a block reaches the same sinks
+ * a post does instead of dying in the ledger.
+ *
+ * The `text` is the ask itself, front-loaded — a notification banner shows roughly
+ * two lines, and a phone message is scanned, not read. `focus` carries the literal
+ * command that unblocks it, so the message the operator receives contains the one
+ * action they have to take rather than making them go find the session.
+ *
+ * Level is always `important`: a block is by definition an agent that has stopped
+ * making progress, so there is no per-block level flag to get wrong.
+ */
+export declare function blockBroadcastContext(block: {
+    blockId: string;
+    sessionId: string;
+    host?: string;
+    questions?: Array<{
+        text?: string;
+    }>;
+    blockClass?: string;
+    costOfDelay?: string;
+    ticket?: string;
+    pr?: string;
+}, extras?: {
+    project?: string;
+    agent?: string;
+}): FeedBroadcastContext;
+/**
+ * Why a declared block reached nobody, or undefined when it got through.
+ *
+ * Pure so the fail-loud contract is testable without driving the CLI — the
+ * original version lived inline in the command action and was consequently
+ * never covered, which is how a `--json` early-return quietly bypassed it.
+ *
+ * Only a TOTAL failure counts. One sink failing among several is a warning, not
+ * an error: the channels are redundant by design, and a dead `rush` login must
+ * not mask a delivered desktop notification.
+ */
+export declare function blockDeliveryFailure(blocked: boolean, outcomes: SinkOutcome[]): string | undefined;
 export interface PlannedSink {
     name: string;
     argv: string[];

package/dist/lib/feed-broadcast.js

@@ -35,6 +35,61 @@ export function parseFeedPostLevel(raw) {
         return 'important';
     throw new Error(`Unknown --level '${raw}'. Use milestone or important.`);
 }
+/**
+ * Map an open block onto the broadcast context, so a block reaches the same sinks
+ * a post does instead of dying in the ledger.
+ *
+ * The `text` is the ask itself, front-loaded — a notification banner shows roughly
+ * two lines, and a phone message is scanned, not read. `focus` carries the literal
+ * command that unblocks it, so the message the operator receives contains the one
+ * action they have to take rather than making them go find the session.
+ *
+ * Level is always `important`: a block is by definition an agent that has stopped
+ * making progress, so there is no per-block level flag to get wrong.
+ */
+export function blockBroadcastContext(block, extras = {}) {
+    const ask = block.questions?.[0]?.text?.trim() || 'agent is blocked';
+    const links = [block.pr].filter((l) => !!l && /^https?:\/\//i.test(l));
+    return {
+        text: ask,
+        level: 'important',
+        ticket: block.ticket,
+        project: extras.project,
+        agent: extras.agent,
+        host: block.host,
+        session: block.sessionId,
+        blockId: block.blockId,
+        class: block.blockClass,
+        cost: block.costOfDelay,
+        // Short id: `agents focus` matches on a prefix, and a full uuid in a phone
+        // message is noise the operator has to skip past to reach the verb.
+        focus: `agents focus ${block.sessionId.slice(0, 8)}`,
+        ...(links.length ? { links } : {}),
+    };
+}
+/**
+ * Why a declared block reached nobody, or undefined when it got through.
+ *
+ * Pure so the fail-loud contract is testable without driving the CLI — the
+ * original version lived inline in the command action and was consequently
+ * never covered, which is how a `--json` early-return quietly bypassed it.
+ *
+ * Only a TOTAL failure counts. One sink failing among several is a warning, not
+ * an error: the channels are redundant by design, and a dead `rush` login must
+ * not mask a delivered desktop notification.
+ */
+export function blockDeliveryFailure(blocked, outcomes) {
+    if (!blocked)
+        return undefined;
+    if (outcomes.length === 0) {
+        return 'Block recorded but NOT delivered — no feed.broadcast sink configured.';
+    }
+    if (outcomes.every((o) => !o.ok)) {
+        const why = outcomes.map((o) => `${o.name}: ${o.error ?? 'failed'}`).join('; ');
+        return `Block recorded but NOT delivered — every feed.broadcast sink failed (${why}).`;
+    }
+    return undefined;
+}
 const PLACEHOLDER = /\{([a-z]+)\}/g;
 /**
  * A human-facing one-liner for a messaging sink: what project, what happened,
@@ -45,7 +100,12 @@ const PLACEHOLDER = /\{([a-z]+)\}/g;
 export function composeBroadcastMessage(ctx) {
     const head = ctx.project ? `${ctx.project} · ${ctx.text}` : ctx.text;
     const link = ctx.links?.find((l) => /^https?:\/\//i.test(l));
-    return link ? `${head}\n${link}` : head;
+    // A block's second line is the command that unblocks it. The operator reading
+    // this on a phone should not have to go find the session — the one action they
+    // must take travels with the ask. A status post has no such action, so it keeps
+    // the link there instead.
+    const tail = [ctx.focus, link].filter(Boolean);
+    return tail.length ? `${head}\n${tail.join('\n')}` : head;
 }
 /** The values a template may reference, resolved once per post. */
 function templateVars(ctx) {
@@ -59,6 +119,10 @@ function templateVars(ctx) {
         level: ctx.level,
         links: ctx.links?.length ? ctx.links.join(' ') : undefined,
         message: composeBroadcastMessage(ctx),
+        block: ctx.blockId,
+        class: ctx.class,
+        cost: ctx.cost,
+        focus: ctx.focus,
     };
 }
 /**

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

@@ -9,6 +9,16 @@ export interface FeedPostInput {
     sessionId?: string;
     /** Generic artifacts to attach: local paths (copied for durability) or URLs. */
     attach?: string[];
+    /**
+     * The agent is STUCK, not merely reporting. Writes `status.blocked` instead of
+     * `status.posted`, and the caller pairs it with an OpenBlock so the ask stays
+     * answerable until someone resolves it.
+     *
+     * This is a state, not a volume: a blocked post is always broadcast at
+     * `important`, so an agent never has to decide the level as well. One thing to
+     * say is what makes the habit stick.
+     */
+    blocked?: boolean;
     /** Override activity root (tests). */
     activityRoot?: string;
     /**

package/dist/lib/feed-post.js

@@ -15,7 +15,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
-import { appendActivityEvent, projectFromCwd, } from './activity.js';
+import { appendActivityEvent, } from './activity.js';
+import { resolveProjectNameForCwd, listProjectDefs } from './projects.js';
 import { getHistoryDir } from './state.js';
 import { machineId } from './machine-id.js';
 import { isValidMailboxId } from './mailbox.js';
@@ -263,7 +264,12 @@ export function postFeedStatus(input) {
             + '(AGENT_SESSION_ID / AGENTS_MAILBOX_DIR / pid registry), or pass --session <id>.');
     }
     const ts = input.ts ?? new Date().toISOString();
-    const project = projectFromCwd(identity.cwd);
+    // The post is written where the agent runs, so the cwd is a local path and
+    // gets full canonical resolution — a defined project's name wins (a post from
+    // any repo of a multi-repo project files under that project), else the repo
+    // key, matching how the timeline groups everything else. listProjectDefs is
+    // fail-open, so this costs one small readdir + YAML parse per post.
+    const project = resolveProjectNameForCwd(identity.cwd, listProjectDefs());
     const attachments = buildAttachments(input.attach, {
         copyRoot: input.attachmentsRoot ?? path.join(getHistoryDir(), 'attachments'),
         sessionId: identity.sessionId,
@@ -271,7 +277,7 @@ export function postFeedStatus(input) {
     });
     const event = {
         ts,
-        event: 'status.posted',
+        event: input.blocked ? 'status.blocked' : 'status.posted',
         sessionId: identity.sessionId,
         mailboxId: identity.mailboxId,
         host: identity.host,

package/dist/lib/feed.d.ts

@@ -38,7 +38,20 @@ export interface OpenBlock {
     runtime: string;
     ts: string;
     questions: BlockQuestion[];
-    kind?: 'question' | 'notification' | 'control';
+    /**
+     * How this block came to exist.
+     *   question     — an AskUserQuestion the harness surfaced
+     *   notification — a permission/idle prompt the harness raised
+     *   control      — a synthetic card the feed itself computed (runaway, needy)
+     *   declared     — the AGENT decided it is stuck and said so (`feed post --blocked`)
+     *
+     * `declared` is the only kind that does not depend on the harness noticing
+     * anything. Every other kind is inferred from a harness event, and hook events
+     * are not portable across harnesses (only Claude fires Notification, only Codex
+     * fires PermissionRequest), so a declared block is the one signal every agent
+     * can raise — it is just a shell command.
+     */
+    kind?: 'question' | 'notification' | 'control' | 'declared';
     notificationType?: string;
     ticket?: string;
     pr?: string;
@@ -159,6 +172,39 @@ export declare function recordNotified(blockId: string, root?: string): void;
 export declare function recordTerminalAnswer(blockId: string, root?: string): void;
 /** Remove answered marker and receipts for a block (used by block removal/GC). */
 export declare function clearBlockLifecycle(blockId: string, root?: string): void;
+/** Identity of the agent declaring a block — the subset of `PostIdentity` it needs. */
+export interface DeclaringAgent {
+    sessionId: string;
+    mailboxId: string;
+    host: string;
+    runtime: string;
+}
+export interface DeclareBlockInput {
+    /** What the agent needs from the user, front-loaded. */
+    text: string;
+    /** Answerable choices, if the ask is a pick-one. */
+    options?: string[];
+    /** A safe default makes this an approval; without one it is a decision. */
+    safeDefault?: string;
+    /** Minutes before the default-on-no-answer policy may fire. */
+    timeoutMinutes?: number;
+    ts?: string;
+}
+/**
+ * Build the block record for `agents feed post --blocked` — pure, so the shape is testable
+ * without touching the store or the broadcast layer.
+ *
+ * Class is derived, not asked for: a `--default` means the user could be absent
+ * and policy could still resolve it (approval); no default means only a human can
+ * choose (decision). `feed-policy.ts` reads exactly that distinction, so deriving
+ * it here keeps one rule in one place instead of letting a caller set a class that
+ * contradicts its own safeDefault.
+ *
+ * `costOfDelay: high` because a declared block is, by definition, an agent that
+ * has already stopped making progress — that is what makes it worth interrupting
+ * someone over, and what `feed --dispatch`'s urgency filter keys off.
+ */
+export declare function buildDeclaredBlock(agent: DeclaringAgent, input: DeclareBlockInput): OpenBlock;
 /** Atomic write a block record to the feed store. Clears stale lifecycle state. */
 export declare function publishBlock(block: OpenBlock, root?: string): void;
 /** Read all block records. Returns them sorted by stable block filename. */

package/dist/lib/feed.js

@@ -236,6 +236,44 @@ export function clearBlockLifecycle(blockId, root) {
         }
     }
 }
+/**
+ * Build the block record for `agents feed post --blocked` — pure, so the shape is testable
+ * without touching the store or the broadcast layer.
+ *
+ * Class is derived, not asked for: a `--default` means the user could be absent
+ * and policy could still resolve it (approval); no default means only a human can
+ * choose (decision). `feed-policy.ts` reads exactly that distinction, so deriving
+ * it here keeps one rule in one place instead of letting a caller set a class that
+ * contradicts its own safeDefault.
+ *
+ * `costOfDelay: high` because a declared block is, by definition, an agent that
+ * has already stopped making progress — that is what makes it worth interrupting
+ * someone over, and what `feed --dispatch`'s urgency filter keys off.
+ */
+export function buildDeclaredBlock(agent, input) {
+    const text = input.text.trim().replace(/\s+/g, ' ');
+    if (!text) {
+        throw new Error('Block text is empty. Usage: agents feed post "what you need from the user" --blocked');
+    }
+    const options = (input.options ?? [])
+        .map((label) => label.trim())
+        .filter(Boolean)
+        .map((label) => ({ label }));
+    return {
+        blockId: blockIdForSession(agent.sessionId),
+        sessionId: agent.sessionId,
+        mailboxId: agent.mailboxId,
+        host: agent.host,
+        runtime: agent.runtime,
+        ts: input.ts ?? new Date().toISOString(),
+        kind: 'declared',
+        questions: [{ text, header: 'Needs you', ...(options.length ? { options } : {}) }],
+        blockClass: input.safeDefault ? 'approval' : 'decision',
+        costOfDelay: 'high',
+        ...(input.safeDefault ? { safeDefault: input.safeDefault } : {}),
+        ...(input.timeoutMinutes !== undefined ? { timeoutMinutes: input.timeoutMinutes } : {}),
+    };
+}
 /** Atomic write a block record to the feed store. Clears stale lifecycle state. */
 export function publishBlock(block, root) {
     const dir = root ?? getFeedDir();

package/dist/lib/hooks/cache.d.ts

@@ -26,6 +26,8 @@ export interface HookShimPaths {
     shimsDir?: string;
     cacheDir?: string;
     logsDir?: string;
+    /** Directory for the disposable perf warehouse + spool (default ~/.agents/.cache/perf). */
+    perfDir?: string;
 }
 /**
  * Generate (or refresh) the shim script for a hook. Idempotent — only writes