@phnx-labs/agents-cli 1.20.92 → 1.20.93

package/dist/index.js

@@ -147,11 +147,25 @@ function auditCommandPath(cmd) {
     return parts;
 }
 const auditStarts = new WeakMap();
+/**
+ * Commands that WRITE the event stream, so recording their own invocation would
+ * add records to the log they are writing into. `events emit` is batched — one
+ * flush every few seconds per open editor window — so auditing it would bury the
+ * real events under two `command.*` records per flush. `_internal friction`
+ * exists for the same reason (shell guards fire before any `agents` process
+ * exists, so they cannot emit in-process) and had the same self-logging bug.
+ */
+const AUDIT_EXEMPT_COMMANDS = new Set([
+    'events emit',
+    '_internal friction',
+]);
 program.hook('preAction', (_thisCommand, actionCommand) => {
     try {
         const parts = auditCommandPath(actionCommand);
         if (parts.length === 0)
             return;
+        if (AUDIT_EXEMPT_COMMANDS.has(parts.join(' ')))
+            return;
         auditStarts.set(actionCommand, Date.now());
         emit('command.start', {
             module: parts[0],
@@ -172,6 +186,8 @@ program.hook('postAction', (_thisCommand, actionCommand) => {
         const parts = auditCommandPath(actionCommand);
         if (parts.length === 0)
             return;
+        if (AUDIT_EXEMPT_COMMANDS.has(parts.join(' ')))
+            return;
         const started = auditStarts.get(actionCommand);
         const durationMs = started !== undefined ? Date.now() - started : undefined;
         const command = parts.join(' ');

package/dist/lib/activity.d.ts

@@ -5,6 +5,14 @@ export type MilestoneEvent = 'plan.created' | 'pr.opened' | 'pr.merged' | 'workt
  | 'video.rendered' | 'video.converted' | 'image.upscaled' | 'metadata.edited'
 /** Deliberate agent-authored progress post (`agents feed post`). */
  | 'status.posted'
+/**
+ * An agent terminal spawned from the Factory VS Code extension. A milestone
+ * because it is the BIRTH of a session — it carries the sessionId and the
+ * terminalId that every later event on that session joins through, the same
+ * way `subagent.spawned` roots a sub-agent. Written out of process by
+ * `agents events emit`; the other factory.* kinds are operational-only.
+ */
+ | 'factory.launch'
 /**
  * The same post, but the agent is STUCK (`agents feed post --blocked`).
  *

package/dist/lib/activity.js

@@ -43,6 +43,12 @@ export const MILESTONE_EVENTS = [
     'image.upscaled',
     'metadata.edited',
     'status.posted',
+    // NOTE: intentionally absent from the Python hook's own MILESTONE_EVENTS copy
+    // (see ACTIVITY_LOG_HOOK_SCRIPT below) — that set only classifies events the
+    // hook itself writes from PreToolUse/PostToolUse, and the hook never writes
+    // this one. activity.test.ts pins the difference so the divergence stays
+    // deliberate rather than becoming drift.
+    'factory.launch',
     'status.blocked',
 ];
 const MILESTONE_SET = new Set(MILESTONE_EVENTS);
@@ -302,6 +308,7 @@ export const EVENT_STYLE = {
     'checklist.created': { glyph: '☐', color: chalk.cyan, label: 'checklist created' },
     'status.posted': { glyph: '▸', color: chalk.white, label: 'status' },
     'file.edited': { glyph: '·', color: chalk.gray, label: 'file edited' },
+    'factory.launch': { glyph: '⌁', color: chalk.cyan, label: 'factory launch' },
     'bash.executed': { glyph: '$', color: chalk.gray, label: 'command run' },
 };
 export function styleForEvent(event) {

package/dist/lib/channels/send.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Delivery envelope for `agents send` / `agents notify`.
+ *
+ * One primitive: resolve a destination (channel + target), compose text + urls +
+ * attachments, hand off to a channel provider. `notify` is the same path with
+ * destination defaulted to `notify.owner` in agents.yaml — owner is an address
+ * alias (`--to owner`), not a separate stack.
+ *
+ * Agent control (`agents message`, `sessions inject`) stays outside this module.
+ */
+import type { Meta } from '../types.js';
+import type { SendResult } from './registry.js';
+/** Normalized delivery request after CLI/config resolution. */
+export interface SendEnvelope {
+    text: string;
+    channel: string;
+    to: string;
+    thread?: string;
+    attachments?: string[];
+    from?: string;
+    dryRun?: boolean;
+}
+export interface ResolveSendInput {
+    /**
+     * Body text. Prefer `--text`; positional `[text]` is accepted for compat and
+     * folded in when `--text` is omitted.
+     */
+    text?: string;
+    /** Positional `[text]` from commander (legacy). */
+    positionalText?: string;
+    /**
+     * Recipient. Channel-specific id, or the alias `owner` which expands to
+     * `notify.owner.{channel,to}`.
+     */
+    to?: string;
+    /** Provider/channel name. Required unless `to` is `owner` (or ownerMode). */
+    channel?: string;
+    thread?: string;
+    /** Local file paths. */
+    attachments?: string[];
+    /** Links / remote media refs — appended to the body so every provider sees them. */
+    urls?: string[];
+    from?: string;
+    dryRun?: boolean;
+    /**
+     * When true (`agents notify`), missing channel/to default to `notify.owner`.
+     * Explicit flags still win.
+     */
+    ownerMode?: boolean;
+}
+export type ResolveSendResult = {
+    ok: true;
+    envelope: SendEnvelope;
+} | {
+    ok: false;
+    error: string;
+};
+/** True when the destination token means “the configured owner”. */
+export declare function isOwnerAlias(to: string | undefined): boolean;
+/** Compose body + optional URL lines (skip urls already present in the body). */
+export declare function composeSendText(text: string, urls?: string[]): string;
+/** Read notify.owner; null when either field is missing. */
+export declare function readOwnerDest(meta: Meta): {
+    channel: string;
+    to: string;
+} | null;
+/**
+ * Resolve CLI/config into a send envelope. Pure except for reading `meta` —
+ * no I/O, no provider registration — so unit tests do not need a real PATH.
+ */
+export declare function resolveSendEnvelope(input: ResolveSendInput, meta: Meta): ResolveSendResult;
+/**
+ * Register providers, resolve transport, deliver. Used by the CLI and by any
+ * internal caller that already has a resolved envelope.
+ */
+export declare function deliverEnvelope(envelope: SendEnvelope, meta: Meta): Promise<SendResult>;
+/** Resolve + deliver in one step (CLI happy path). */
+export declare function sendMessage(input: ResolveSendInput, meta: Meta): Promise<{
+    result: SendResult;
+    envelope: SendEnvelope;
+} | {
+    error: string;
+}>;

package/dist/lib/channels/send.js

@@ -0,0 +1,112 @@
+import { registerBuiltinProviders } from './providers/index.js';
+import { resolveTransport } from './resolve.js';
+const OWNER_ALIAS = 'owner';
+/** True when the destination token means “the configured owner”. */
+export function isOwnerAlias(to) {
+    return (to ?? '').trim().toLowerCase() === OWNER_ALIAS;
+}
+/** Compose body + optional URL lines (skip urls already present in the body). */
+export function composeSendText(text, urls) {
+    const body = text.trim();
+    const extra = (urls ?? [])
+        .map((u) => u.trim())
+        .filter(Boolean)
+        .filter((u) => !body.includes(u));
+    if (extra.length === 0)
+        return body;
+    return body ? `${body}\n${extra.join('\n')}` : extra.join('\n');
+}
+/** Read notify.owner; null when either field is missing. */
+export function readOwnerDest(meta) {
+    const owner = meta.notify?.owner;
+    const channel = owner?.channel?.trim();
+    const to = owner?.to?.trim();
+    if (!channel || !to)
+        return null;
+    return { channel, to };
+}
+/**
+ * Resolve CLI/config into a send envelope. Pure except for reading `meta` —
+ * no I/O, no provider registration — so unit tests do not need a real PATH.
+ */
+export function resolveSendEnvelope(input, meta) {
+    const positional = (input.positionalText ?? '').trim();
+    const flagged = (input.text ?? '').trim();
+    if (positional && flagged && positional !== flagged) {
+        return {
+            ok: false,
+            error: 'Pass the message once: use --text, or a positional argument, not both with different values.',
+        };
+    }
+    const rawText = flagged || positional;
+    const urls = (input.urls ?? []).map((u) => u.trim()).filter(Boolean);
+    const text = composeSendText(rawText, urls);
+    if (!text) {
+        return {
+            ok: false,
+            error: 'Message is empty. Pass --text "…", a positional message, and/or --url.',
+        };
+    }
+    // Owner defaults fill only missing fields (and expand the bare "owner" alias).
+    // Explicit --channel/--to always win; a complete notify.owner is NOT required
+    // when both flags are already set (same merge-then-require shape as main).
+    const ownerCfg = meta.notify?.owner;
+    const ownerChannel = ownerCfg?.channel?.trim() || '';
+    const ownerTo = ownerCfg?.to?.trim() || '';
+    let channel = (input.channel ?? '').trim();
+    let to = (input.to ?? '').trim();
+    const usedOwnerAlias = isOwnerAlias(to);
+    if (input.ownerMode || usedOwnerAlias) {
+        if (!channel)
+            channel = ownerChannel;
+        if (!to || usedOwnerAlias)
+            to = ownerTo;
+    }
+    if (!channel || !to) {
+        const hint = input.ownerMode || usedOwnerAlias
+            ? 'Set notify.owner.{channel,to} in agents.yaml, or pass --channel and --to explicitly.'
+            : 'Need --channel and --to (or --to owner with notify.owner configured). ' +
+                'Example: agents send --channel desktop --to local --text "hi"';
+        return { ok: false, error: hint };
+    }
+    const attachments = [
+        ...(input.attachments ?? []),
+    ]
+        .map((p) => p.trim())
+        .filter(Boolean);
+    return {
+        ok: true,
+        envelope: {
+            text,
+            channel,
+            to,
+            thread: input.thread?.trim() || undefined,
+            attachments: attachments.length ? attachments : undefined,
+            from: input.from?.trim() || undefined,
+            dryRun: input.dryRun,
+        },
+    };
+}
+/**
+ * Register providers, resolve transport, deliver. Used by the CLI and by any
+ * internal caller that already has a resolved envelope.
+ */
+export async function deliverEnvelope(envelope, meta) {
+    registerBuiltinProviders();
+    const provider = resolveTransport(envelope.channel, meta);
+    return provider.send(envelope.text, {
+        target: envelope.to,
+        thread: envelope.thread,
+        attachments: envelope.attachments,
+        from: envelope.from,
+        dryRun: envelope.dryRun,
+    });
+}
+/** Resolve + deliver in one step (CLI happy path). */
+export async function sendMessage(input, meta) {
+    const resolved = resolveSendEnvelope(input, meta);
+    if (!resolved.ok)
+        return { error: resolved.error };
+    const result = await deliverEnvelope(resolved.envelope, meta);
+    return { result, envelope: resolved.envelope };
+}

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

@@ -13,7 +13,11 @@
  */
 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;
@@ -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.

package/dist/lib/events.js

@@ -72,9 +72,50 @@ function isDisabled() {
 const DIR_MODE = 0o700;
 /** File permissions (owner read/write only). */
 const FILE_MODE = 0o600;
+/**
+ * Every {@link EventType}, as a runtime-checkable table.
+ *
+ * Typed `Record<EventType, true>` on purpose: the object literal is
+ * exhaustiveness-checked at COMPILE time, so adding a member to the union
+ * without adding it here fails `tsc`. That is what keeps the runtime validator
+ * (`isEventType`, used by `agents events emit` to reject an unknown kind from an
+ * out-of-process producer) from silently drifting behind the union.
+ */
+const EVENT_TYPE_TABLE = {
+    'agent.run.start': true, 'agent.run.end': true, 'agent.spawn.start': true, 'agent.spawn.end': true,
+    'version.install': true, 'version.switch': true, 'version.remove': true,
+    'skill.install': true, 'skill.remove': true,
+    'browser.launch': true, 'browser.close': true, 'browser.navigate': true, 'browser.screenshot': true,
+    'secrets.get': true, 'secrets.unlocked': true, 'secrets.create': true, 'secrets.import': true, 'secrets.export': true, 'secrets.view': true, 'secrets.set': true, 'secrets.delete': true, 'secrets.rename': true,
+    'cloud.dispatch': true, 'cloud.complete': true, 'cloud.cancel': true, 'cloud.message': true,
+    'teams.create': true, 'teams.add': true, 'teams.start': true, 'teams.complete': true, 'teams.disband': true,
+    'hook.fire': true, 'hook.complete': true, 'hook.error': true,
+    'mcp.add': true, 'mcp.remove': true, 'mcp.register': true,
+    'resource.sync': true,
+    'rotation.resolved': true,
+    'command.start': true, 'command.end': true,
+    'perf.timing': true,
+    'session.start': true, 'session.end': true,
+    'webhook.received': true, 'webhook.authorized': true, 'webhook.rejected': true, 'webhook.matched': true,
+    'webhook.fired': true, 'webhook.handler.start': true, 'webhook.handler.end': true,
+    'plan.created': true, 'pr.opened': true, 'pr.merged': true, 'worktree.created': true,
+    'worktree.removed': true, 'commit.created': true, 'pushed': true, 'subagent.spawned': true,
+    'artifact.created': true, 'task.completed': true, 'checklist.created': true, 'status.posted': true,
+    'file.edited': true,
+    'factory.command': true, 'factory.action': true, 'factory.uri': true, 'factory.launch': true,
+    'friction': true, 'error': true, 'warn': true, 'info': true, 'debug': true,
+};
+/** Every known event kind. Derived from {@link EVENT_TYPE_TABLE}, never hand-listed. */
+export const EVENT_TYPES = Object.keys(EVENT_TYPE_TABLE);
+const EVENT_TYPE_SET = new Set(EVENT_TYPES);
+/** Runtime guard for an event kind arriving from outside this process. */
+export function isEventType(value) {
+    return EVENT_TYPE_SET.has(value);
+}
 const AUDIT_EVENTS = new Set([
     'command.start', 'command.end',
-    'secrets.get', 'secrets.unlocked', 'secrets.set', 'secrets.delete', 'secrets.rename',
+    'secrets.get', 'secrets.unlocked', 'secrets.create', 'secrets.import', 'secrets.export', 'secrets.view',
+    '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',
@@ -82,6 +123,11 @@ const AUDIT_EVENTS = new Set([
     'mcp.add', 'mcp.remove', 'mcp.register',
     'rotation.resolved',
     'session.start', 'session.end',
+    // An external process reaching into the user's editor (the CLI's
+    // vscodium-agent backend driving `/spawn` / `/inject` / `/focus`) is a
+    // "who reached in from outside" fact, which is what the audit lane answers.
+    // The other factory.* kinds are ordinary info — a palette press is not audit.
+    'factory.uri',
 ]);
 export function levelFor(event) {
     if (event === 'warn')
@@ -334,8 +380,14 @@ function resolveProvenance(env = process.env) {
  *
  * @param event - The event type
  * @param payload - Event-specific data (agent, version, cwd, etc.)
+ * @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 function emit(event, payload = {}) {
+export function emit(event, payload = {}, overrides = {}) {
     if (isDisabled())
         return;
     try {
@@ -346,7 +398,7 @@ export function emit(event, payload = {}) {
             // Provenance floor first: env-sourced defaults an explicit payload overrides.
             ...resolveProvenance(),
             ...safePayload,
-            ts: new Date().toISOString(),
+            ts: overrides.ts ?? new Date().toISOString(),
             tz: getTimezoneOffset(),
             tzName: getTimezoneName(),
             hostname: os.hostname(),