@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/lib/device-config.js

@@ -0,0 +1,296 @@
+/**
+ * Device/user config keys — typed read/write over the two-tier agents.yaml store.
+ *
+ * One registry (`CONFIG_KEYS`) maps each CLI dotted name to where it lives:
+ *   - user scope   → central `~/.agents/agents.yaml` under `config:` (syncs
+ *                    fleet-wide via `agents repo push/pull`)
+ *   - device scope → `~/.agents/devices/<host>/agents.yaml` under `config:`
+ *                    (per-machine; mirrors how `defaultBrowserProfile` is routed)
+ *
+ * This machine's keys go through the readMeta/updateMeta funnel (state.ts) so the
+ * partition/overlay logic stays the single writer. Another device's doc is
+ * read/written in place — the devices/ tree syncs via the DotAgents repo, so
+ * editing `devices/mac-mini/agents.yaml` locally is how `configure`/`note`
+ * target a peer (`--device`-style).
+ *
+ * `browser.profile` is NOT a `config:` key — it is the existing
+ * `Meta.defaultBrowserProfile` field; the registry entry documents the mapping
+ * and set/get route to it so there is one source of truth (no duplicate key).
+ *
+ * Unset always means today's behavior.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { META_HEADER, getUserAgentsDir, readMeta, updateMeta } from './state.js';
+import { atomicWriteFileSync } from './fs-atomic.js';
+import { machineId } from './machine-id.js';
+import { assertValidDeviceName } from './devices/registry.js';
+export const CONFIG_KEYS = [
+    {
+        name: 'interactive.host',
+        yamlKey: 'interactiveHost',
+        scope: 'user',
+        type: 'string',
+        description: 'Device that shows the user artifacts (browser opens, dashboards) — the "online macOS box" skills should use instead of guessing.',
+        validate: (v) => {
+            try {
+                assertValidDeviceName(v);
+                return null;
+            }
+            catch (err) {
+                return err?.message ?? String(err);
+            }
+        },
+    },
+    {
+        name: 'browser.profile',
+        yamlKey: 'defaultBrowserProfile',
+        scope: 'device',
+        type: 'string',
+        field: 'defaultBrowserProfile',
+        description: 'Browser profile `agents browser start` resolves to without --profile (set via `agents browser profiles set-default`).',
+    },
+    {
+        name: 'agents.max-concurrent',
+        yamlKey: 'maxAgents',
+        scope: 'device',
+        type: 'int',
+        description: 'Cap on concurrent agents on this device. What counts toward it depends on the consumer: ' +
+            'Factory auto-launch counts device-wide running agents; teams placement counts the team’s own roster on the device.',
+        validate: (v) => (v >= 1 ? null : 'agents.max-concurrent must be >= 1.'),
+    },
+    {
+        name: 'scheduler.enabled',
+        yamlKey: 'schedulerEnabled',
+        scope: 'device',
+        type: 'bool',
+        description: 'Whether the routines scheduler (daemon) may fire on this device.',
+    },
+    {
+        name: 'notes',
+        yamlKey: 'notes',
+        scope: 'device',
+        type: 'string-list',
+        description: 'Free-form operator notes about this device (one entry per `agents devices note`).',
+    },
+];
+/** Look up a key spec by CLI dotted name, or throw listing the known keys. */
+export function configKeySpec(name) {
+    const spec = CONFIG_KEYS.find((k) => k.name === name);
+    if (!spec) {
+        throw new Error(`Unknown config key '${name}'. Known keys: ${CONFIG_KEYS.map((k) => k.name).join(', ')}.`);
+    }
+    return spec;
+}
+/** Throw when `value` does not match the key's declared type or validation. */
+function assertValidValue(spec, value) {
+    switch (spec.type) {
+        case 'string':
+            if (typeof value !== 'string' || value.length === 0) {
+                throw new Error(`Config key '${spec.name}' expects a non-empty string, got ${JSON.stringify(value)}.`);
+            }
+            break;
+        case 'int':
+            if (!Number.isInteger(value)) {
+                throw new Error(`Config key '${spec.name}' expects an integer, got ${JSON.stringify(value)}.`);
+            }
+            break;
+        case 'bool':
+            if (typeof value !== 'boolean') {
+                throw new Error(`Config key '${spec.name}' expects a boolean, got ${JSON.stringify(value)}.`);
+            }
+            break;
+        case 'string-list':
+            if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+                throw new Error(`Config key '${spec.name}' expects a list of strings, got ${JSON.stringify(value)}.`);
+            }
+            break;
+    }
+    const err = spec.validate?.(value);
+    if (err)
+        throw new Error(`Invalid value for '${spec.name}': ${err}`);
+}
+// ─── Sibling-device doc access ────────────────────────────────────────────────
+/** Path to any device's doc (self or a peer) under the synced devices/ tree. */
+function deviceDocPath(device) {
+    return path.join(getUserAgentsDir(), 'devices', device, 'agents.yaml');
+}
+/**
+ * Read a device doc directly. Returns null when the file does not exist. A
+ * malformed file is a hard error — silently returning null would let the next
+ * write wipe the device's pins/default (same contract as the device registry).
+ * A valid-but-non-map document (a bare string, a list) is the same kind of
+ * corruption: reject it here instead of failing later with a TypeError.
+ */
+function readDeviceDoc(device) {
+    const p = deviceDocPath(device);
+    let raw;
+    try {
+        raw = fs.readFileSync(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    const corrupted = (detail) => new Error(`Device config corrupted at ${p}: ${detail}. Inspect and restore from backup.`);
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch (err) {
+        throw corrupted(err?.message ?? String(err));
+    }
+    if (parsed === null || parsed === undefined)
+        return {};
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw corrupted(`expected a YAML map, got ${Array.isArray(parsed) ? 'a list' : JSON.stringify(parsed)}`);
+    }
+    return parsed;
+}
+/** Write a device doc in place (atomic). Only ever holds device-local fields. */
+function writeDeviceDoc(device, doc) {
+    const p = deviceDocPath(device);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const body = Object.keys(doc).length > 0 ? doc : { agents: {} };
+    atomicWriteFileSync(p, META_HEADER + yaml.stringify(body));
+}
+// ─── Reads ────────────────────────────────────────────────────────────────────
+function entryFromMeta(spec, meta) {
+    if (spec.field === 'defaultBrowserProfile') {
+        const value = meta.defaultBrowserProfile;
+        return { spec, value, layer: value !== undefined ? 'device' : undefined };
+    }
+    if (spec.scope === 'user') {
+        const value = meta.config?.[spec.yamlKey];
+        return { spec, value, layer: value !== undefined ? 'user' : undefined };
+    }
+    const value = meta.deviceConfig?.[spec.yamlKey];
+    return { spec, value, layer: value !== undefined ? 'device' : undefined };
+}
+/** True when `device` names this machine (case-insensitive, mirroring
+ * `isLocalDevice` in teams/scheduler.ts) — `configure ZION` on host zion must
+ * take the self path (readMeta/updateMeta funnel), not the peer-doc path. */
+function isSelfDevice(device) {
+    return device.toLowerCase() === machineId();
+}
+/** Get one config key's value and the layer that set it. */
+export function getConfigValue(name, opts) {
+    const spec = configKeySpec(name);
+    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
+        const doc = readDeviceDoc(opts.device) ?? {};
+        return entryFromMeta(spec, { deviceConfig: doc.config, defaultBrowserProfile: doc.defaultBrowserProfile });
+    }
+    return entryFromMeta(spec, readMeta());
+}
+/** List every known key with its value and the layer that set it. */
+export function listConfig(opts) {
+    return CONFIG_KEYS.map((spec) => getConfigValue(spec.name, opts));
+}
+// ─── Writes ───────────────────────────────────────────────────────────────────
+function setInMeta(spec, value) {
+    updateMeta((m) => {
+        if (spec.field === 'defaultBrowserProfile') {
+            return { ...m, defaultBrowserProfile: value };
+        }
+        if (spec.scope === 'user') {
+            return { ...m, config: { ...m.config, [spec.yamlKey]: value } };
+        }
+        return { ...m, deviceConfig: { ...m.deviceConfig, [spec.yamlKey]: value } };
+    });
+}
+function unsetInMeta(spec) {
+    updateMeta((m) => {
+        if (spec.field === 'defaultBrowserProfile') {
+            const { defaultBrowserProfile, ...rest } = m;
+            void defaultBrowserProfile;
+            return rest;
+        }
+        const block = spec.scope === 'user' ? m.config : m.deviceConfig;
+        if (!block || !(spec.yamlKey in block))
+            return m;
+        const next = { ...block };
+        delete next[spec.yamlKey];
+        const cleaned = Object.keys(next).length > 0 ? next : undefined;
+        return spec.scope === 'user' ? { ...m, config: cleaned } : { ...m, deviceConfig: cleaned };
+    });
+}
+function setInDeviceDoc(device, spec, value) {
+    const doc = readDeviceDoc(device) ?? {};
+    if (spec.field === 'defaultBrowserProfile') {
+        doc.defaultBrowserProfile = value;
+    }
+    else {
+        doc.config = { ...doc.config, [spec.yamlKey]: value };
+    }
+    writeDeviceDoc(device, doc);
+}
+function unsetInDeviceDoc(device, spec) {
+    const doc = readDeviceDoc(device);
+    if (!doc)
+        return; // nothing stored — unset is a no-op
+    if (spec.field === 'defaultBrowserProfile') {
+        delete doc.defaultBrowserProfile;
+    }
+    else if (doc.config && spec.yamlKey in doc.config) {
+        delete doc.config[spec.yamlKey];
+        if (Object.keys(doc.config).length === 0)
+            delete doc.config;
+    }
+    else {
+        return; // key not present — no write needed
+    }
+    writeDeviceDoc(device, doc);
+}
+/** Set a config key (validated). Device-scope keys target this machine unless `opts.device` names a peer. */
+export function setConfigValue(name, value, opts) {
+    const spec = configKeySpec(name);
+    assertValidValue(spec, value);
+    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
+        setInDeviceDoc(opts.device, spec, value);
+        return;
+    }
+    setInMeta(spec, value);
+}
+/** Unset a config key — restores default behavior. No-op when already unset. */
+export function unsetConfigValue(name, opts) {
+    const spec = configKeySpec(name);
+    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
+        unsetInDeviceDoc(opts.device, spec);
+        return;
+    }
+    unsetInMeta(spec);
+}
+// ─── Consumers' helpers ───────────────────────────────────────────────────────
+/** True unless this machine's device doc disables the routines scheduler. */
+export function isSchedulerEnabled() {
+    return getConfigValue('scheduler.enabled').value !== false;
+}
+/**
+ * Throw when the routines scheduler is disabled on this machine, naming the
+ * setting and the fix. The single message every scheduler-start surface
+ * (auto-start on `routines add`, manual `routines start`, the daemon's own
+ * scheduler init) refuses with.
+ */
+export function assertSchedulerEnabled() {
+    if (isSchedulerEnabled())
+        return;
+    throw new Error(`The routines scheduler is disabled on this device (scheduler.enabled=false in ~/.agents/devices/${machineId()}/agents.yaml). ` +
+        `Re-enable with: agents devices configure ${machineId()} --scheduler on`);
+}
+/**
+ * Read the `agents.max-concurrent` cap for each named device from its synced
+ * device doc (no SSH). Devices without a cap are omitted — uncapped is the
+ * default. Used as an input to host ranking (teams placement, Factory
+ * auto-launch), never as a remote probe.
+ */
+export function readMaxConcurrentCaps(devices) {
+    const caps = {};
+    for (const device of devices) {
+        const value = getConfigValue('agents.max-concurrent', { device }).value;
+        if (typeof value === 'number')
+            caps[device] = value;
+    }
+    return caps;
+}

package/dist/lib/event-provenance.d.ts

@@ -0,0 +1,19 @@
+import { type ActorKind } from './actor.js';
+export interface EventProvenance {
+    osUser: string;
+    transport: 'local' | 'ssh';
+    sshClientIp?: string;
+    actor: string;
+    kind: ActorKind;
+    machineId: string;
+    sessionId?: string;
+    agent?: string;
+    launchId?: string;
+    parentSessionId?: string;
+}
+/**
+ * Stamp the shared identity floor used by both operational and activity events.
+ * Explicit event payload fields may override these defaults at the call site.
+ */
+export declare function stampProvenance(env?: NodeJS.ProcessEnv): EventProvenance;
+export declare function resetEventProvenanceForTest(): void;

package/dist/lib/event-provenance.js

@@ -0,0 +1,48 @@
+import * as os from 'os';
+import { resolveActor } from './actor.js';
+import { machineId } from './machine-id.js';
+import { parseSshConnection } from './session/provenance.js';
+let cachedOrigin;
+let cachedDeviceId;
+/**
+ * Stamp the shared identity floor used by both operational and activity events.
+ * Explicit event payload fields may override these defaults at the call site.
+ */
+export function stampProvenance(env = process.env) {
+    if (!cachedOrigin) {
+        let osUser = 'unknown';
+        try {
+            osUser = os.userInfo().username;
+        }
+        catch {
+            // A uid without a passwd entry has no attributable OS user.
+        }
+        const ssh = env.SSH_CONNECTION ? parseSshConnection(env.SSH_CONNECTION) : undefined;
+        const actor = resolveActor();
+        cachedOrigin = {
+            osUser,
+            transport: ssh ? 'ssh' : 'local',
+            ...(ssh ? { sshClientIp: ssh.clientIp } : {}),
+            actor: actor.id,
+            kind: actor.kind,
+        };
+    }
+    const provenance = {
+        ...cachedOrigin,
+        machineId: (cachedDeviceId ??= machineId()),
+    };
+    const sessionId = env.AGENT_SESSION_ID || env.AGENTS_SESSION_ID;
+    if (sessionId)
+        provenance.sessionId = sessionId;
+    if (env.AGENTS_AGENT_NAME)
+        provenance.agent = env.AGENTS_AGENT_NAME;
+    if (env.AGENT_LAUNCH_ID)
+        provenance.launchId = env.AGENT_LAUNCH_ID;
+    if (env.AGENTS_PARENT_SESSION_ID)
+        provenance.parentSessionId = env.AGENTS_PARENT_SESSION_ID;
+    return provenance;
+}
+export function resetEventProvenanceForTest() {
+    cachedOrigin = undefined;
+    cachedDeviceId = undefined;
+}

package/dist/lib/events-ingest.d.ts

@@ -0,0 +1,46 @@
+export interface IngestReject {
+    /** 1-based index of the offending line within the batch. */
+    line: number;
+    reason: string;
+}
+export interface IngestResult {
+    written: number;
+    rejected: IngestReject[];
+    /** Per-store counts, so a caller/test can assert routing without reading files. */
+    routed: {
+        operational: number;
+        activity: number;
+    };
+}
+export interface IngestOptions {
+    /**
+     * Producer name, stamped as `module` on operational records so
+     * `agents events --module <source>` filters to this producer. Required: an
+     * unattributed external event is not auditable.
+     */
+    source: string;
+    /** Validate and report without writing either store. */
+    dryRun?: boolean;
+    /** Override the activity root (tests). */
+    activityRoot?: string;
+}
+/**
+ * Route one already-validated line.
+ *
+ * The rule is forced by the stores, not chosen:
+ *   - The activity store is keyed by session id ON DISK (one file per session),
+ *     so an event with no session has nowhere to live there.
+ *   - Activity records are read back with `module: 'activity'` hardcoded, so
+ *     anything that must stay filterable by its producer has to be operational.
+ * Therefore: milestone + usable sessionId -> activity; everything else -> ops.
+ * `readUnifiedEvents` merges the two at read time, so `agents events` sees both.
+ */
+export declare function routeFor(event: string, sessionId: unknown): 'activity' | 'operational';
+/**
+ * Ingest a JSONL batch.
+ *
+ * Rejection is PER LINE and lossless: a single bad line never discards the rest
+ * of the batch. One typo in a 100-event flush must not silently drop 99 real
+ * events, and the caller still learns exactly which line failed and why.
+ */
+export declare function ingestBatch(input: string, opts: IngestOptions): IngestResult;

package/dist/lib/events-ingest.js

@@ -0,0 +1,182 @@
+/**
+ * Ingest events produced OUTSIDE this process — the writer behind
+ * `agents events emit`.
+ *
+ * Why this exists: `emit()` (lib/events.ts) and `appendActivityEvent()`
+ * (lib/activity.ts) are in-process APIs, but the producers that most need to
+ * record events are not agents-cli processes at all — the Factory VS Code
+ * extension host, a shell guard, any external tool. They shell out instead, and
+ * this module is the one place that turns their JSONL into real records.
+ *
+ * It deliberately does NOT reuse `feed post`: that surface hardcodes the
+ * `status.posted` kind, infers identity by walking the pid-registry ancestor
+ * chain (wrong for a process that is not a descendant of an agent), throws when
+ * that inference fails, and fires the configured broadcast sinks. A telemetry
+ * path must do none of those things.
+ *
+ * Pure except for the two writers it calls, so the routing and validation rules
+ * below are unit-testable against a temp events path + activity root.
+ */
+import { emit, isEventType, } from './events.js';
+import { appendActivityEvent, tierForEvent, } from './activity.js';
+/** Envelope keys an incoming line may set directly; everything else is payload. */
+const ENVELOPE_KEYS = [
+    'event', 'ts', 'sessionId', 'mailboxId', 'terminalId', 'launchId', 'tmuxPane',
+    'host', 'runtime', 'agent', 'tool', 'detail', 'url', 'project', 'cwd',
+];
+const ENVELOPE_KEY_SET = new Set(ENVELOPE_KEYS);
+/** ISO-8601 with at least seconds. Rejects "now", epoch ints, and garbage. */
+function isIsoTimestamp(value) {
+    if (typeof value !== 'string')
+        return false;
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value))
+        return false;
+    return !Number.isNaN(Date.parse(value));
+}
+/**
+ * A session id must be non-empty AND survive the activity writer's filename
+ * sanitizer — `activityPath` throws on an id that reduces to nothing, and that
+ * throw would abort a whole batch mid-write. Check it here so the line is
+ * rejected cleanly and its siblings still land.
+ */
+function isUsableSessionId(value) {
+    return typeof value === 'string' && value.replace(/[^A-Za-z0-9._-]/g, '-').replace(/-+/g, '') !== '';
+}
+/**
+ * Route one already-validated line.
+ *
+ * The rule is forced by the stores, not chosen:
+ *   - The activity store is keyed by session id ON DISK (one file per session),
+ *     so an event with no session has nowhere to live there.
+ *   - Activity records are read back with `module: 'activity'` hardcoded, so
+ *     anything that must stay filterable by its producer has to be operational.
+ * Therefore: milestone + usable sessionId -> activity; everything else -> ops.
+ * `readUnifiedEvents` merges the two at read time, so `agents events` sees both.
+ */
+export function routeFor(event, sessionId) {
+    return tierForEvent(event) === 'milestone' && isUsableSessionId(sessionId) ? 'activity' : 'operational';
+}
+/** Validate one raw JSONL line. Returns either a parsed line or a rejection. */
+function parseLine(raw, lineNo) {
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return { line: lineNo, reason: 'not valid JSON' };
+    }
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+        return { line: lineNo, reason: 'not a JSON object' };
+    }
+    const rec = obj;
+    const event = rec.event;
+    if (typeof event !== 'string' || event === '') {
+        return { line: lineNo, reason: 'missing "event"' };
+    }
+    if (!isEventType(event)) {
+        return { line: lineNo, reason: `unknown event kind: ${event}` };
+    }
+    if (rec.ts !== undefined && !isIsoTimestamp(rec.ts)) {
+        return { line: lineNo, reason: `invalid "ts" (want ISO-8601): ${String(rec.ts)}` };
+    }
+    // A milestone with no usable session id is REJECTED, not quietly demoted to
+    // the operational store. Silently writing it somewhere else would look like
+    // success while the event never appears in the activity lane the producer
+    // asked for -- exactly the "wrong path that looks like success" this codebase
+    // forbids at a boundary.
+    if (tierForEvent(event) === 'milestone' && !isUsableSessionId(rec.sessionId)) {
+        return {
+            line: lineNo,
+            reason: `"${event}" is a milestone and needs a non-empty "sessionId" (the activity log is keyed by it)`,
+        };
+    }
+    const envelope = {};
+    const payload = {};
+    for (const [key, value] of Object.entries(rec)) {
+        if (key === 'event' || key === 'ts')
+            continue;
+        if (ENVELOPE_KEY_SET.has(key))
+            envelope[key] = value;
+        else
+            payload[key] = value;
+    }
+    return { line: lineNo, event, ts: rec.ts, envelope, payload };
+}
+function str(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+/**
+ * Ingest a JSONL batch.
+ *
+ * Rejection is PER LINE and lossless: a single bad line never discards the rest
+ * of the batch. One typo in a 100-event flush must not silently drop 99 real
+ * events, and the caller still learns exactly which line failed and why.
+ */
+export function ingestBatch(input, opts) {
+    const source = opts.source.trim();
+    if (!source)
+        throw new Error('events emit: --source is required (it names the producer)');
+    const result = { written: 0, rejected: [], routed: { operational: 0, activity: 0 } };
+    const rawLines = input.split('\n');
+    let lineNo = 0;
+    for (const raw of rawLines) {
+        lineNo += 1;
+        if (raw.trim() === '')
+            continue;
+        const parsed = parseLine(raw, lineNo);
+        if ('reason' in parsed) {
+            result.rejected.push(parsed);
+            continue;
+        }
+        const route = routeFor(parsed.event, parsed.envelope.sessionId);
+        result.routed[route] += 1;
+        if (opts.dryRun) {
+            result.written += 1;
+            continue;
+        }
+        if (route === 'activity') {
+            const sessionId = parsed.envelope.sessionId;
+            const ev = {
+                ts: parsed.ts ?? new Date().toISOString(),
+                event: parsed.event,
+                sessionId,
+                mailboxId: str(parsed.envelope.mailboxId) ?? sessionId,
+                host: str(parsed.envelope.host) ?? '',
+                runtime: str(parsed.envelope.runtime) ?? source,
+                ...(str(parsed.envelope.cwd) ? { cwd: parsed.envelope.cwd } : {}),
+                ...(str(parsed.envelope.project) ? { project: parsed.envelope.project } : {}),
+                ...(str(parsed.envelope.agent) ? { agent: parsed.envelope.agent } : {}),
+                ...(str(parsed.envelope.tool) ? { tool: parsed.envelope.tool } : {}),
+                ...(str(parsed.envelope.detail) ? { detail: parsed.envelope.detail } : {}),
+                ...(str(parsed.envelope.url) ? { url: parsed.envelope.url } : {}),
+                ...(str(parsed.envelope.launchId) ? { launchId: parsed.envelope.launchId } : {}),
+                ...(str(parsed.envelope.terminalId) ? { terminalId: parsed.envelope.terminalId } : {}),
+                ...(str(parsed.envelope.tmuxPane) ? { tmuxPane: parsed.envelope.tmuxPane } : {}),
+            };
+            appendActivityEvent(ev, opts.activityRoot);
+            result.written += 1;
+            continue;
+        }
+        // Operational. `module: source` is what makes `--module factory` work;
+        // the envelope fields that have no EventPayload home ride along as payload
+        // keys, where sanitizePayload still applies its redaction rules.
+        const payload = {
+            module: source,
+            ...parsed.payload,
+            ...(str(parsed.envelope.sessionId) ? { sessionId: parsed.envelope.sessionId } : {}),
+            ...(str(parsed.envelope.agent) ? { agent: parsed.envelope.agent } : {}),
+            ...(str(parsed.envelope.cwd) ? { cwd: parsed.envelope.cwd } : {}),
+            ...(str(parsed.envelope.project) ? { project: parsed.envelope.project } : {}),
+            ...(str(parsed.envelope.detail) ? { detail: parsed.envelope.detail } : {}),
+            ...(str(parsed.envelope.url) ? { url: parsed.envelope.url } : {}),
+            ...(str(parsed.envelope.terminalId) ? { terminalId: parsed.envelope.terminalId } : {}),
+            ...(str(parsed.envelope.launchId) ? { launchId: parsed.envelope.launchId } : {}),
+            ...(str(parsed.envelope.host) ? { sourceHost: parsed.envelope.host } : {}),
+            ...(str(parsed.envelope.runtime) ? { runtime: parsed.envelope.runtime } : {}),
+            ...(str(parsed.envelope.tool) ? { tool: parsed.envelope.tool } : {}),
+        };
+        emit(parsed.event, payload, parsed.ts ? { ts: parsed.ts } : {});
+        result.written += 1;
+    }
+    return result;
+}

package/dist/lib/events.d.ts

@@ -11,9 +11,13 @@
  * - Permissions: logs dir is 0700, files are 0600 (owner-only)
  * - Performance tracking: withTiming() wrapper for any async function
  */
-import { type ActorKind } from './actor.js';
+import type { ActorKind } from './actor.js';
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
+/** Every known event kind. Derived from {@link EVENT_TYPE_TABLE}, never hand-listed. */
+export declare const EVENT_TYPES: readonly EventType[];
+/** Runtime guard for an event kind arriving from outside this process. */
+export declare function isEventType(value: string): value is EventType;
 export declare function levelFor(event: EventType): EventLevel;
 export interface EventMeta {
     ts: string;
@@ -42,7 +46,7 @@ export interface EventMeta {
     /** Resolved actor id — which human/agent is behind this event (RUSH-2020). */
     actor?: string;
     /** Actor kind (`human`/`agent`). */
-    kind?: ActorKind;
+    kind?: ActorKind | 'unknown';
 }
 export interface EventPayload {
     agent?: string;
@@ -100,8 +104,16 @@ export declare function detectCaller(env?: NodeJS.ProcessEnv, stdoutIsTTY?: bool
  *
  * @param event - The event type
  * @param payload - Event-specific data (agent, version, cwd, etc.)
- */
-export declare function emit(event: EventType, payload?: EventPayload): void;
+ * @param overrides - Envelope fields the CALLER owns rather than the writer.
+ *   Only `ts` today: a batched out-of-process producer (`agents events emit`)
+ *   records when each event HAPPENED, but flushes them together later, so
+ *   stamping write-time would collapse a whole batch onto the flush instant and
+ *   corrupt every `--since` boundary. `ts` stays in RESERVED_META_KEYS so a
+ *   *payload* still cannot inject it — this explicit channel is the only way in.
+ */
+export declare function emit(event: EventType, payload?: EventPayload, overrides?: {
+    ts?: string;
+}): void;
 /**
  * Convenience wrapper for timed operations.
  * Returns a function to call when the operation completes.