@nubemclaw/agent-events 1.2.2

package/dist/agent-events.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Verbose level (port verbatim OpenClaw `auto-reply/thinking.shared.ts:18`).
+ *
+ * `off` silences agent commentary; `on` emits standard logs;
+ * `full` includes diagnostic detail. Surfaced here so run contexts
+ * carry the level without coupling agent-events to a thinking module.
+ */
+export type VerboseLevel = "off" | "on" | "full";
+export type AgentEventStream = "lifecycle" | "tool" | "assistant" | "error" | "item" | "plan" | "approval" | "command_output" | "patch" | "compaction" | "thinking" | (string & {});
+export type AgentItemEventPhase = "start" | "update" | "end";
+export type AgentItemEventStatus = "running" | "completed" | "failed" | "blocked";
+export type AgentItemEventKind = "tool" | "command" | "patch" | "search" | "analysis" | (string & {});
+export type AgentItemEventData = {
+    itemId: string;
+    phase: AgentItemEventPhase;
+    kind: AgentItemEventKind;
+    title: string;
+    status: AgentItemEventStatus;
+    name?: string;
+    meta?: string;
+    toolCallId?: string;
+    startedAt?: number;
+    endedAt?: number;
+    error?: string;
+    summary?: string;
+    progressText?: string;
+    /** Preserve item telemetry while letting channel progress render a sibling tool event instead. */
+    suppressChannelProgress?: boolean;
+    approvalId?: string;
+    approvalSlug?: string;
+};
+export type AgentPlanEventData = {
+    phase: "update";
+    title: string;
+    explanation?: string;
+    steps?: string[];
+    source?: string;
+};
+export type AgentApprovalEventPhase = "requested" | "resolved";
+export type AgentApprovalEventStatus = "pending" | "unavailable" | "approved" | "denied" | "failed";
+export type AgentApprovalEventKind = "exec" | "plugin" | "unknown";
+export type AgentApprovalEventData = {
+    phase: AgentApprovalEventPhase;
+    kind: AgentApprovalEventKind;
+    status: AgentApprovalEventStatus;
+    title: string;
+    itemId?: string;
+    toolCallId?: string;
+    approvalId?: string;
+    approvalSlug?: string;
+    command?: string;
+    host?: string;
+    reason?: string;
+    scope?: "turn" | "session";
+    message?: string;
+};
+export type AgentCommandOutputEventData = {
+    itemId: string;
+    phase: "delta" | "end";
+    title: string;
+    toolCallId: string;
+    name?: string;
+    output?: string;
+    status?: AgentItemEventStatus | "running";
+    exitCode?: number | null;
+    durationMs?: number;
+    cwd?: string;
+};
+export type AgentPatchSummaryEventData = {
+    itemId: string;
+    phase: "end";
+    title: string;
+    toolCallId: string;
+    name?: string;
+    added: string[];
+    modified: string[];
+    deleted: string[];
+    summary: string;
+};
+export type AgentEventPayload = {
+    runId: string;
+    seq: number;
+    stream: AgentEventStream;
+    ts: number;
+    data: Record<string, unknown>;
+    sessionKey?: string;
+};
+export type AgentRunContext = {
+    sessionKey?: string;
+    verboseLevel?: VerboseLevel;
+    isHeartbeat?: boolean;
+    /** Whether control UI clients should receive chat/agent updates for this run. */
+    isControlUiVisible?: boolean;
+    /** Timestamp when this context was first registered (for TTL-based cleanup). */
+    registeredAt?: number;
+    /** Timestamp of last activity (updated on every emitAgentEvent). */
+    lastActiveAt?: number;
+};
+export declare function registerAgentRunContext(runId: string, context: AgentRunContext): void;
+export declare function getAgentRunContext(runId: string): AgentRunContext | undefined;
+export declare function clearAgentRunContext(runId: string): void;
+/**
+ * Sweep stale run contexts that exceeded the given TTL.
+ * Guards against orphaned entries when lifecycle "end"/"error" events are missed.
+ */
+export declare function sweepStaleRunContexts(maxAgeMs?: number): number;
+export declare function resetAgentRunContextForTest(): void;
+export declare function emitAgentEvent(event: Omit<AgentEventPayload, "seq" | "ts">): void;
+export declare function emitAgentItemEvent(params: {
+    runId: string;
+    data: AgentItemEventData;
+    sessionKey?: string;
+}): void;
+export declare function emitAgentPlanEvent(params: {
+    runId: string;
+    data: AgentPlanEventData;
+    sessionKey?: string;
+}): void;
+export declare function emitAgentApprovalEvent(params: {
+    runId: string;
+    data: AgentApprovalEventData;
+    sessionKey?: string;
+}): void;
+export declare function emitAgentCommandOutputEvent(params: {
+    runId: string;
+    data: AgentCommandOutputEventData;
+    sessionKey?: string;
+}): void;
+export declare function emitAgentPatchSummaryEvent(params: {
+    runId: string;
+    data: AgentPatchSummaryEventData;
+    sessionKey?: string;
+}): void;
+export declare function onAgentEvent(listener: (evt: AgentEventPayload) => void): () => void;
+export declare function resetAgentEventsForTest(): void;
+//# sourceMappingURL=agent-events.d.ts.map

package/dist/agent-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-events.d.ts","sourceRoot":"","sources":["../src/agent-events.ts"],"names":[],"mappings":"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"}

package/dist/agent-events.js

@@ -0,0 +1,187 @@
+/**
+ * agent-events — port verbatim de
+ * `~/Desktop/GitHub/openclaw/src/infra/agent-events.ts:1-312`.
+ *
+ * In-process event bus para agent lifecycle/tool/assistant/etc. La
+ * elección del singleton mediante `globalThis[Symbol.for(...)]` (no
+ * un módulo-state local) sobrevive a chunks de runtime split (ESM
+ * bundles, vitest worker pools, sub-process forks que se re-importan
+ * el módulo). El contrato observable es el corazón de cómo TUI
+ * embedded, gateway HTTP/WS y daemon se "atan" sin acoplarse — todos
+ * los runners suben el mismo bus, todos los listeners ven el mismo
+ * stream.
+ *
+ * Cambios mínimos frente al verbatim OpenClaw:
+ *
+ *   1. `Symbol.for("openclaw.agentEvents.state")` →
+ *      `Symbol.for("nubemclaw.agentEvents.state")` por la regla de
+ *      rebrand canónico ADR-0003 (la palabra "openclaw" no aparece
+ *      en código v3 fuera de comentarios de ingeniería inversa).
+ *   2. `VerboseLevel` inline (declarado aquí, no importado de un
+ *      módulo `auto-reply/thinking.shared.ts` que v3 no tiene).
+ *      Tomado verbatim de OpenClaw thinking.shared.ts:18.
+ *   3. `emitAgentEvent` construye `enriched` con spread condicional
+ *      cuando `sessionKey === undefined`, porque v3 usa
+ *      `exactOptionalPropertyTypes: true` y no permite asignar
+ *      `undefined` a un campo `?: string`. Shape semantics idénticas.
+ *   4. Imports relativos con extensión `.js` (NodeNext ESM v3).
+ *
+ * El resto (símbolos, line shape, comentarios sustanciales,
+ * orden de funciones) se preserva 1:1.
+ */
+import { resolveGlobalSingleton } from "./global-singleton.js";
+import { notifyListeners, registerListener } from "./listeners.js";
+const AGENT_EVENT_STATE_KEY = Symbol.for("nubemclaw.agentEvents.state");
+function getAgentEventState() {
+    return resolveGlobalSingleton(AGENT_EVENT_STATE_KEY, () => ({
+        seqByRun: new Map(),
+        listeners: new Set(),
+        runContextById: new Map(),
+    }));
+}
+export function registerAgentRunContext(runId, context) {
+    if (!runId) {
+        return;
+    }
+    const state = getAgentEventState();
+    const existing = state.runContextById.get(runId);
+    if (!existing) {
+        const registered = {
+            ...context,
+            registeredAt: context.registeredAt ?? Date.now(),
+        };
+        state.runContextById.set(runId, registered);
+        return;
+    }
+    if (context.sessionKey !== undefined && existing.sessionKey !== context.sessionKey) {
+        existing.sessionKey = context.sessionKey;
+    }
+    if (context.verboseLevel !== undefined && existing.verboseLevel !== context.verboseLevel) {
+        existing.verboseLevel = context.verboseLevel;
+    }
+    if (context.isControlUiVisible !== undefined) {
+        existing.isControlUiVisible = context.isControlUiVisible;
+    }
+    if (context.isHeartbeat !== undefined && existing.isHeartbeat !== context.isHeartbeat) {
+        existing.isHeartbeat = context.isHeartbeat;
+    }
+    if (context.registeredAt !== undefined) {
+        existing.registeredAt = context.registeredAt;
+    }
+    if (context.lastActiveAt !== undefined) {
+        existing.lastActiveAt = context.lastActiveAt;
+    }
+}
+export function getAgentRunContext(runId) {
+    return getAgentEventState().runContextById.get(runId);
+}
+export function clearAgentRunContext(runId) {
+    const state = getAgentEventState();
+    state.runContextById.delete(runId);
+    state.seqByRun.delete(runId);
+}
+/**
+ * Sweep stale run contexts that exceeded the given TTL.
+ * Guards against orphaned entries when lifecycle "end"/"error" events are missed.
+ */
+export function sweepStaleRunContexts(maxAgeMs = 30 * 60 * 1000) {
+    const state = getAgentEventState();
+    const now = Date.now();
+    let swept = 0;
+    for (const [runId, ctx] of state.runContextById.entries()) {
+        // Use lastActiveAt (refreshed on every event) to avoid sweeping active runs.
+        // Fall back to registeredAt, then treat missing timestamps as infinitely old.
+        const lastSeen = ctx.lastActiveAt ?? ctx.registeredAt;
+        const age = lastSeen ? now - lastSeen : Infinity;
+        if (age > maxAgeMs) {
+            state.runContextById.delete(runId);
+            state.seqByRun.delete(runId);
+            swept++;
+        }
+    }
+    return swept;
+}
+export function resetAgentRunContextForTest() {
+    const state = getAgentEventState();
+    state.runContextById.clear();
+    state.seqByRun.clear();
+}
+export function emitAgentEvent(event) {
+    const state = getAgentEventState();
+    const nextSeq = (state.seqByRun.get(event.runId) ?? 0) + 1;
+    state.seqByRun.set(event.runId, nextSeq);
+    const context = state.runContextById.get(event.runId);
+    if (context) {
+        context.lastActiveAt = Date.now();
+    }
+    const isControlUiVisible = context?.isControlUiVisible ?? true;
+    const eventSessionKey = typeof event.sessionKey === "string" && event.sessionKey.trim() ? event.sessionKey : undefined;
+    // Hidden channel-routed runs should not leak live assistant/tool traffic into
+    // Control UI, but lifecycle events still need the session key so gateway
+    // listeners can persist terminal session state even if run-context lookup is
+    // unavailable by the time the terminal event arrives. Terminal failures are
+    // emitted on the lifecycle stream with `phase: "error"`; the separate error
+    // stream remains redacted for hidden runs because it is observational only.
+    const preserveSessionKey = isControlUiVisible || event.stream === "lifecycle";
+    const sessionKey = preserveSessionKey ? (eventSessionKey ?? context?.sessionKey) : undefined;
+    const enriched = {
+        runId: event.runId,
+        stream: event.stream,
+        data: event.data,
+        seq: nextSeq,
+        ts: Date.now(),
+        ...(sessionKey !== undefined ? { sessionKey } : {}),
+    };
+    notifyListeners(state.listeners, enriched);
+}
+export function emitAgentItemEvent(params) {
+    emitAgentEvent({
+        runId: params.runId,
+        stream: "item",
+        data: params.data,
+        ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+    });
+}
+export function emitAgentPlanEvent(params) {
+    emitAgentEvent({
+        runId: params.runId,
+        stream: "plan",
+        data: params.data,
+        ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+    });
+}
+export function emitAgentApprovalEvent(params) {
+    emitAgentEvent({
+        runId: params.runId,
+        stream: "approval",
+        data: params.data,
+        ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+    });
+}
+export function emitAgentCommandOutputEvent(params) {
+    emitAgentEvent({
+        runId: params.runId,
+        stream: "command_output",
+        data: params.data,
+        ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+    });
+}
+export function emitAgentPatchSummaryEvent(params) {
+    emitAgentEvent({
+        runId: params.runId,
+        stream: "patch",
+        data: params.data,
+        ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+    });
+}
+export function onAgentEvent(listener) {
+    const state = getAgentEventState();
+    return registerListener(state.listeners, listener);
+}
+export function resetAgentEventsForTest() {
+    const state = getAgentEventState();
+    state.seqByRun.clear();
+    state.listeners.clear();
+    state.runContextById.clear();
+}
+//# sourceMappingURL=agent-events.js.map

package/dist/agent-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-events.js","sourceRoot":"","sources":["../src/agent-events.ts"],"names":[],"mappings":"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"}

package/dist/global-singleton.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Port verbatim de `~/Desktop/GitHub/openclaw/src/shared/global-singleton.ts:1-17`.
+ *
+ * Safe for process-local caches and registries that can tolerate helper-based
+ * resolution. Do not use this for live mutable state that must survive split
+ * runtime chunks; keep those on a direct `globalThis[Symbol.for(...)]` lookup.
+ */
+export declare function resolveGlobalSingleton<T>(key: symbol, create: () => T): T;
+export declare function resolveGlobalMap<TKey, TValue>(key: symbol): Map<TKey, TValue>;
+//# sourceMappingURL=global-singleton.d.ts.map

package/dist/global-singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-singleton.d.ts","sourceRoot":"","sources":["../src/global-singleton.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAQzE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAE7E"}

package/dist/global-singleton.js

@@ -0,0 +1,20 @@
+/**
+ * Port verbatim de `~/Desktop/GitHub/openclaw/src/shared/global-singleton.ts:1-17`.
+ *
+ * Safe for process-local caches and registries that can tolerate helper-based
+ * resolution. Do not use this for live mutable state that must survive split
+ * runtime chunks; keep those on a direct `globalThis[Symbol.for(...)]` lookup.
+ */
+export function resolveGlobalSingleton(key, create) {
+    const globalStore = globalThis;
+    if (Object.prototype.hasOwnProperty.call(globalStore, key)) {
+        return globalStore[key];
+    }
+    const created = create();
+    globalStore[key] = created;
+    return created;
+}
+export function resolveGlobalMap(key) {
+    return resolveGlobalSingleton(key, () => new Map());
+}
+//# sourceMappingURL=global-singleton.js.map

package/dist/global-singleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-singleton.js","sourceRoot":"","sources":["../src/global-singleton.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAI,GAAW,EAAE,MAAe;IACpE,MAAM,WAAW,GAAG,UAA0C,CAAC;IAC/D,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,CAAC;QAC3D,OAAO,WAAW,CAAC,GAAG,CAAM,CAAC;IAC/B,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAe,GAAW;IACxD,OAAO,sBAAsB,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,GAAG,EAAgB,CAAC,CAAC;AACpE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @nubemclaw/agent-events — public surface.
+ *
+ * Re-exports the in-process bus + helpers + types from `agent-events.ts`.
+ * Consumers in this repo (`packages/cli`, `packages/gateway`,
+ * `packages/channel-telegram`, future `packages/gateway-client`) import
+ * from this entrypoint only — never reach inside `src/agent-events.ts`.
+ *
+ * The two infra helpers `resolveGlobalSingleton` and
+ * `notifyListeners`/`registerListener` are intentionally NOT re-exported:
+ * they support the bus implementation, not its public contract.
+ */
+export type { AgentApprovalEventData, AgentApprovalEventKind, AgentApprovalEventPhase, AgentApprovalEventStatus, AgentCommandOutputEventData, AgentEventPayload, AgentEventStream, AgentItemEventData, AgentItemEventKind, AgentItemEventPhase, AgentItemEventStatus, AgentPatchSummaryEventData, AgentPlanEventData, AgentRunContext, VerboseLevel, } from "./agent-events.js";
+export { clearAgentRunContext, emitAgentApprovalEvent, emitAgentCommandOutputEvent, emitAgentEvent, emitAgentItemEvent, emitAgentPatchSummaryEvent, emitAgentPlanEvent, getAgentRunContext, onAgentEvent, registerAgentRunContext, resetAgentEventsForTest, resetAgentRunContextForTest, sweepStaleRunContexts, } from "./agent-events.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,2BAA2B,EAC3B,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,eAAe,EACf,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EACZ,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { clearAgentRunContext, emitAgentApprovalEvent, emitAgentCommandOutputEvent, emitAgentEvent, emitAgentItemEvent, emitAgentPatchSummaryEvent, emitAgentPlanEvent, getAgentRunContext, onAgentEvent, registerAgentRunContext, resetAgentEventsForTest, resetAgentRunContextForTest, sweepStaleRunContexts, } from "./agent-events.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA8BA,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EACZ,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,mBAAmB,CAAC"}

package/dist/listeners.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Port verbatim de `~/Desktop/GitHub/openclaw/src/shared/listeners.ts:1-22`.
+ *
+ * `notifyListeners` swallows individual listener errors via `onError?` so a
+ * misbehaving subscriber cannot break the fan-out. `registerListener` returns
+ * an unsubscribe callback in the same shape `onAgentEvent` consumers expect.
+ */
+export declare function notifyListeners<T>(listeners: Iterable<(event: T) => void>, event: T, onError?: (error: unknown) => void): void;
+export declare function registerListener<T>(listeners: Set<(event: T) => void>, listener: (event: T) => void): () => void;
+//# sourceMappingURL=listeners.d.ts.map

package/dist/listeners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../src/listeners.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,SAAS,EAAE,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,EACvC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACjC,IAAI,CAQN;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,SAAS,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,EAClC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAC3B,MAAM,IAAI,CAKZ"}

package/dist/listeners.js

@@ -0,0 +1,24 @@
+/**
+ * Port verbatim de `~/Desktop/GitHub/openclaw/src/shared/listeners.ts:1-22`.
+ *
+ * `notifyListeners` swallows individual listener errors via `onError?` so a
+ * misbehaving subscriber cannot break the fan-out. `registerListener` returns
+ * an unsubscribe callback in the same shape `onAgentEvent` consumers expect.
+ */
+export function notifyListeners(listeners, event, onError) {
+    for (const listener of listeners) {
+        try {
+            listener(event);
+        }
+        catch (error) {
+            onError?.(error);
+        }
+    }
+}
+export function registerListener(listeners, listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+//# sourceMappingURL=listeners.js.map

package/dist/listeners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.js","sourceRoot":"","sources":["../src/listeners.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAuC,EACvC,KAAQ,EACR,OAAkC;IAElC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,SAAkC,EAClC,QAA4B;IAE5B,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxB,OAAO,GAAG,EAAE;QACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@nubemclaw/agent-events",
+  "version": "1.2.2",
+  "description": "NubemClaw v3 — in-process event-bus para agent lifecycle (port verbatim OpenClaw src/infra/agent-events.ts). Singleton via globalThis Symbol; cross-fase contract observable.",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean && rm -rf dist .cache"
+  }
+}

package/src/agent-events.test.ts

@@ -0,0 +1,356 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import type { AgentEventPayload } from "./agent-events.js";
+import {
+  clearAgentRunContext,
+  emitAgentApprovalEvent,
+  emitAgentCommandOutputEvent,
+  emitAgentEvent,
+  emitAgentItemEvent,
+  emitAgentPatchSummaryEvent,
+  emitAgentPlanEvent,
+  getAgentRunContext,
+  onAgentEvent,
+  registerAgentRunContext,
+  resetAgentEventsForTest,
+  sweepStaleRunContexts,
+} from "./agent-events.js";
+
+/**
+ * Contract tests for the in-process bus. Mirrors the cases covered by
+ * `~/Desktop/GitHub/openclaw/src/infra/agent-events.test.ts` (where
+ * present) plus the visibility-gating semantics asserted by the
+ * dispatcher F19 wiring. The bus uses a `globalThis[Symbol.for(...)]`
+ * singleton so each test must reset state via `resetAgentEventsForTest`.
+ */
+afterEach(() => {
+  resetAgentEventsForTest();
+});
+
+describe("emitAgentEvent + onAgentEvent", () => {
+  it("delivers events to all subscribers in registration order", () => {
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentEvent({ runId: "run-1", stream: "lifecycle", data: { phase: "start" } });
+
+    expect(seen).toHaveLength(1);
+    expect(seen[0]?.runId).toBe("run-1");
+    expect(seen[0]?.stream).toBe("lifecycle");
+    expect(seen[0]?.seq).toBe(1);
+    expect(typeof seen[0]?.ts).toBe("number");
+  });
+
+  it("increments seq per runId (and resets per run)", () => {
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentEvent({ runId: "run-A", stream: "lifecycle", data: { phase: "start" } });
+    emitAgentEvent({ runId: "run-A", stream: "tool", data: { name: "search" } });
+    emitAgentEvent({ runId: "run-B", stream: "lifecycle", data: { phase: "start" } });
+    emitAgentEvent({ runId: "run-A", stream: "lifecycle", data: { phase: "end" } });
+
+    expect(seen.map((e) => `${e.runId}#${e.seq}`)).toEqual([
+      "run-A#1",
+      "run-A#2",
+      "run-B#1",
+      "run-A#3",
+    ]);
+  });
+
+  it("returns an unsubscribe callback that stops further deliveries", () => {
+    const seen: AgentEventPayload[] = [];
+    const unsubscribe = onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentEvent({ runId: "r", stream: "lifecycle", data: { phase: "start" } });
+    unsubscribe();
+    emitAgentEvent({ runId: "r", stream: "lifecycle", data: { phase: "end" } });
+
+    expect(seen).toHaveLength(1);
+    expect(seen[0]?.data).toEqual({ phase: "start" });
+  });
+
+  it("isolates a misbehaving listener so siblings still receive the event", () => {
+    const seen: string[] = [];
+    onAgentEvent(() => {
+      throw new Error("boom");
+    });
+    onAgentEvent((evt) => {
+      seen.push(`${evt.runId}/${evt.stream}`);
+    });
+
+    expect(() =>
+      emitAgentEvent({ runId: "r", stream: "lifecycle", data: { phase: "start" } }),
+    ).not.toThrow();
+    expect(seen).toEqual(["r/lifecycle"]);
+  });
+});
+
+describe("sessionKey enrichment + visibility gating", () => {
+  it("uses an event-level sessionKey verbatim when provided", () => {
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentEvent({
+      runId: "r",
+      stream: "tool",
+      data: { name: "x" },
+      sessionKey: "session-explicit",
+    });
+
+    expect(seen[0]?.sessionKey).toBe("session-explicit");
+  });
+
+  it("falls back to the registered context sessionKey", () => {
+    registerAgentRunContext("r", { sessionKey: "session-from-context" });
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentEvent({ runId: "r", stream: "tool", data: { name: "x" } });
+
+    expect(seen[0]?.sessionKey).toBe("session-from-context");
+  });
+
+  it("treats a blank-or-whitespace event sessionKey as absent", () => {
+    registerAgentRunContext("r", { sessionKey: "context-fallback" });
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentEvent({ runId: "r", stream: "tool", data: { x: 1 }, sessionKey: "   " });
+
+    expect(seen[0]?.sessionKey).toBe("context-fallback");
+  });
+
+  it("redacts sessionKey on non-lifecycle streams when run is hidden", () => {
+    registerAgentRunContext("r", {
+      sessionKey: "hidden-session",
+      isControlUiVisible: false,
+    });
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentEvent({ runId: "r", stream: "tool", data: { name: "x" } });
+
+    expect(seen[0]?.sessionKey).toBeUndefined();
+  });
+
+  it("preserves sessionKey on the lifecycle stream even when hidden", () => {
+    registerAgentRunContext("r", {
+      sessionKey: "hidden-but-lifecycle",
+      isControlUiVisible: false,
+    });
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentEvent({ runId: "r", stream: "lifecycle", data: { phase: "end" } });
+
+    expect(seen[0]?.sessionKey).toBe("hidden-but-lifecycle");
+  });
+});
+
+describe("registerAgentRunContext", () => {
+  it("ignores an empty runId (no-op)", () => {
+    registerAgentRunContext("", { sessionKey: "irrelevant" });
+    expect(getAgentRunContext("")).toBeUndefined();
+  });
+
+  it("creates a fresh entry with registeredAt defaulted to now", () => {
+    const before = Date.now();
+    registerAgentRunContext("r", { sessionKey: "s" });
+    const ctx = getAgentRunContext("r");
+
+    expect(ctx?.sessionKey).toBe("s");
+    expect(ctx?.registeredAt).toBeGreaterThanOrEqual(before);
+  });
+
+  it("merges into an existing entry without overwriting with undefined", () => {
+    registerAgentRunContext("r", { sessionKey: "first", verboseLevel: "full" });
+    registerAgentRunContext("r", { isHeartbeat: true });
+
+    const ctx = getAgentRunContext("r");
+    expect(ctx?.sessionKey).toBe("first");
+    expect(ctx?.verboseLevel).toBe("full");
+    expect(ctx?.isHeartbeat).toBe(true);
+  });
+
+  it("allows toggling isControlUiVisible to false explicitly", () => {
+    registerAgentRunContext("r", { isControlUiVisible: true });
+    registerAgentRunContext("r", { isControlUiVisible: false });
+
+    expect(getAgentRunContext("r")?.isControlUiVisible).toBe(false);
+  });
+});
+
+describe("clearAgentRunContext", () => {
+  it("removes the context entry and its seq counter", () => {
+    registerAgentRunContext("r", { sessionKey: "s" });
+    emitAgentEvent({ runId: "r", stream: "lifecycle", data: { phase: "start" } });
+    emitAgentEvent({ runId: "r", stream: "tool", data: { name: "x" } });
+
+    clearAgentRunContext("r");
+    expect(getAgentRunContext("r")).toBeUndefined();
+
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+    emitAgentEvent({ runId: "r", stream: "lifecycle", data: { phase: "restart" } });
+
+    expect(seen[0]?.seq).toBe(1);
+  });
+});
+
+describe("sweepStaleRunContexts", () => {
+  it("removes entries whose lastActiveAt exceeds the TTL", () => {
+    registerAgentRunContext("old", {
+      registeredAt: Date.now() - 60_000,
+      lastActiveAt: Date.now() - 60_000,
+    });
+    registerAgentRunContext("fresh", { lastActiveAt: Date.now() });
+
+    const swept = sweepStaleRunContexts(30_000);
+
+    expect(swept).toBe(1);
+    expect(getAgentRunContext("old")).toBeUndefined();
+    expect(getAgentRunContext("fresh")).toBeDefined();
+  });
+
+  it("uses registeredAt when lastActiveAt is missing", () => {
+    registerAgentRunContext("partial", { registeredAt: Date.now() - 60_000 });
+
+    const swept = sweepStaleRunContexts(30_000);
+
+    expect(swept).toBe(1);
+    expect(getAgentRunContext("partial")).toBeUndefined();
+  });
+
+  it("treats entries with no timestamp as infinitely old", () => {
+    registerAgentRunContext("ghost", { sessionKey: "abc" });
+    const ctx = getAgentRunContext("ghost");
+    if (ctx) {
+      delete ctx.registeredAt;
+    }
+
+    const swept = sweepStaleRunContexts(30_000);
+
+    expect(swept).toBe(1);
+    expect(getAgentRunContext("ghost")).toBeUndefined();
+  });
+});
+
+describe("typed helpers", () => {
+  it("emitAgentItemEvent emits with stream='item' and forwards sessionKey", () => {
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentItemEvent({
+      runId: "r",
+      sessionKey: "sess",
+      data: {
+        itemId: "item-1",
+        phase: "start",
+        kind: "tool",
+        title: "Run shell",
+        status: "running",
+      },
+    });
+
+    expect(seen[0]?.stream).toBe("item");
+    expect(seen[0]?.sessionKey).toBe("sess");
+    expect(seen[0]?.data).toMatchObject({ itemId: "item-1", phase: "start" });
+  });
+
+  it("emitAgentPlanEvent emits with stream='plan'", () => {
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentPlanEvent({
+      runId: "r",
+      data: { phase: "update", title: "Plan", steps: ["a", "b"] },
+    });
+
+    expect(seen[0]?.stream).toBe("plan");
+  });
+
+  it("emitAgentApprovalEvent emits with stream='approval'", () => {
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentApprovalEvent({
+      runId: "r",
+      data: {
+        phase: "requested",
+        kind: "exec",
+        status: "pending",
+        title: "Approve curl",
+      },
+    });
+
+    expect(seen[0]?.stream).toBe("approval");
+  });
+
+  it("emitAgentCommandOutputEvent emits with stream='command_output'", () => {
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentCommandOutputEvent({
+      runId: "r",
+      data: {
+        itemId: "i",
+        phase: "delta",
+        title: "shell",
+        toolCallId: "tc-1",
+        output: "hello\n",
+      },
+    });
+
+    expect(seen[0]?.stream).toBe("command_output");
+  });
+
+  it("emitAgentPatchSummaryEvent emits with stream='patch'", () => {
+    const seen: AgentEventPayload[] = [];
+    onAgentEvent((evt) => {
+      seen.push(evt);
+    });
+
+    emitAgentPatchSummaryEvent({
+      runId: "r",
+      data: {
+        itemId: "i",
+        phase: "end",
+        title: "Apply patch",
+        toolCallId: "tc-1",
+        added: ["a.ts"],
+        modified: [],
+        deleted: [],
+        summary: "+1/-0",
+      },
+    });
+
+    expect(seen[0]?.stream).toBe("patch");
+  });
+});

package/src/agent-events.ts

@@ -0,0 +1,355 @@
+/**
+ * agent-events — port verbatim de
+ * `~/Desktop/GitHub/openclaw/src/infra/agent-events.ts:1-312`.
+ *
+ * In-process event bus para agent lifecycle/tool/assistant/etc. La
+ * elección del singleton mediante `globalThis[Symbol.for(...)]` (no
+ * un módulo-state local) sobrevive a chunks de runtime split (ESM
+ * bundles, vitest worker pools, sub-process forks que se re-importan
+ * el módulo). El contrato observable es el corazón de cómo TUI
+ * embedded, gateway HTTP/WS y daemon se "atan" sin acoplarse — todos
+ * los runners suben el mismo bus, todos los listeners ven el mismo
+ * stream.
+ *
+ * Cambios mínimos frente al verbatim OpenClaw:
+ *
+ *   1. `Symbol.for("openclaw.agentEvents.state")` →
+ *      `Symbol.for("nubemclaw.agentEvents.state")` por la regla de
+ *      rebrand canónico ADR-0003 (la palabra "openclaw" no aparece
+ *      en código v3 fuera de comentarios de ingeniería inversa).
+ *   2. `VerboseLevel` inline (declarado aquí, no importado de un
+ *      módulo `auto-reply/thinking.shared.ts` que v3 no tiene).
+ *      Tomado verbatim de OpenClaw thinking.shared.ts:18.
+ *   3. `emitAgentEvent` construye `enriched` con spread condicional
+ *      cuando `sessionKey === undefined`, porque v3 usa
+ *      `exactOptionalPropertyTypes: true` y no permite asignar
+ *      `undefined` a un campo `?: string`. Shape semantics idénticas.
+ *   4. Imports relativos con extensión `.js` (NodeNext ESM v3).
+ *
+ * El resto (símbolos, line shape, comentarios sustanciales,
+ * orden de funciones) se preserva 1:1.
+ */
+import { resolveGlobalSingleton } from "./global-singleton.js";
+import { notifyListeners, registerListener } from "./listeners.js";
+
+/**
+ * Verbose level (port verbatim OpenClaw `auto-reply/thinking.shared.ts:18`).
+ *
+ * `off` silences agent commentary; `on` emits standard logs;
+ * `full` includes diagnostic detail. Surfaced here so run contexts
+ * carry the level without coupling agent-events to a thinking module.
+ */
+export type VerboseLevel = "off" | "on" | "full";
+
+export type AgentEventStream =
+  | "lifecycle"
+  | "tool"
+  | "assistant"
+  | "error"
+  | "item"
+  | "plan"
+  | "approval"
+  | "command_output"
+  | "patch"
+  | "compaction"
+  | "thinking"
+  | (string & {});
+
+export type AgentItemEventPhase = "start" | "update" | "end";
+export type AgentItemEventStatus = "running" | "completed" | "failed" | "blocked";
+export type AgentItemEventKind =
+  | "tool"
+  | "command"
+  | "patch"
+  | "search"
+  | "analysis"
+  | (string & {});
+
+export type AgentItemEventData = {
+  itemId: string;
+  phase: AgentItemEventPhase;
+  kind: AgentItemEventKind;
+  title: string;
+  status: AgentItemEventStatus;
+  name?: string;
+  meta?: string;
+  toolCallId?: string;
+  startedAt?: number;
+  endedAt?: number;
+  error?: string;
+  summary?: string;
+  progressText?: string;
+  /** Preserve item telemetry while letting channel progress render a sibling tool event instead. */
+  suppressChannelProgress?: boolean;
+  approvalId?: string;
+  approvalSlug?: string;
+};
+
+export type AgentPlanEventData = {
+  phase: "update";
+  title: string;
+  explanation?: string;
+  steps?: string[];
+  source?: string;
+};
+
+export type AgentApprovalEventPhase = "requested" | "resolved";
+export type AgentApprovalEventStatus = "pending" | "unavailable" | "approved" | "denied" | "failed";
+export type AgentApprovalEventKind = "exec" | "plugin" | "unknown";
+
+export type AgentApprovalEventData = {
+  phase: AgentApprovalEventPhase;
+  kind: AgentApprovalEventKind;
+  status: AgentApprovalEventStatus;
+  title: string;
+  itemId?: string;
+  toolCallId?: string;
+  approvalId?: string;
+  approvalSlug?: string;
+  command?: string;
+  host?: string;
+  reason?: string;
+  scope?: "turn" | "session";
+  message?: string;
+};
+
+export type AgentCommandOutputEventData = {
+  itemId: string;
+  phase: "delta" | "end";
+  title: string;
+  toolCallId: string;
+  name?: string;
+  output?: string;
+  status?: AgentItemEventStatus | "running";
+  exitCode?: number | null;
+  durationMs?: number;
+  cwd?: string;
+};
+
+export type AgentPatchSummaryEventData = {
+  itemId: string;
+  phase: "end";
+  title: string;
+  toolCallId: string;
+  name?: string;
+  added: string[];
+  modified: string[];
+  deleted: string[];
+  summary: string;
+};
+
+export type AgentEventPayload = {
+  runId: string;
+  seq: number;
+  stream: AgentEventStream;
+  ts: number;
+  data: Record<string, unknown>;
+  sessionKey?: string;
+};
+
+export type AgentRunContext = {
+  sessionKey?: string;
+  verboseLevel?: VerboseLevel;
+  isHeartbeat?: boolean;
+  /** Whether control UI clients should receive chat/agent updates for this run. */
+  isControlUiVisible?: boolean;
+  /** Timestamp when this context was first registered (for TTL-based cleanup). */
+  registeredAt?: number;
+  /** Timestamp of last activity (updated on every emitAgentEvent). */
+  lastActiveAt?: number;
+};
+
+type AgentEventState = {
+  seqByRun: Map<string, number>;
+  listeners: Set<(evt: AgentEventPayload) => void>;
+  runContextById: Map<string, AgentRunContext>;
+};
+
+const AGENT_EVENT_STATE_KEY = Symbol.for("nubemclaw.agentEvents.state");
+
+function getAgentEventState(): AgentEventState {
+  return resolveGlobalSingleton<AgentEventState>(AGENT_EVENT_STATE_KEY, () => ({
+    seqByRun: new Map<string, number>(),
+    listeners: new Set<(evt: AgentEventPayload) => void>(),
+    runContextById: new Map<string, AgentRunContext>(),
+  }));
+}
+
+export function registerAgentRunContext(runId: string, context: AgentRunContext): void {
+  if (!runId) {
+    return;
+  }
+  const state = getAgentEventState();
+  const existing = state.runContextById.get(runId);
+  if (!existing) {
+    const registered: AgentRunContext = {
+      ...context,
+      registeredAt: context.registeredAt ?? Date.now(),
+    };
+    state.runContextById.set(runId, registered);
+    return;
+  }
+  if (context.sessionKey !== undefined && existing.sessionKey !== context.sessionKey) {
+    existing.sessionKey = context.sessionKey;
+  }
+  if (context.verboseLevel !== undefined && existing.verboseLevel !== context.verboseLevel) {
+    existing.verboseLevel = context.verboseLevel;
+  }
+  if (context.isControlUiVisible !== undefined) {
+    existing.isControlUiVisible = context.isControlUiVisible;
+  }
+  if (context.isHeartbeat !== undefined && existing.isHeartbeat !== context.isHeartbeat) {
+    existing.isHeartbeat = context.isHeartbeat;
+  }
+  if (context.registeredAt !== undefined) {
+    existing.registeredAt = context.registeredAt;
+  }
+  if (context.lastActiveAt !== undefined) {
+    existing.lastActiveAt = context.lastActiveAt;
+  }
+}
+
+export function getAgentRunContext(runId: string): AgentRunContext | undefined {
+  return getAgentEventState().runContextById.get(runId);
+}
+
+export function clearAgentRunContext(runId: string): void {
+  const state = getAgentEventState();
+  state.runContextById.delete(runId);
+  state.seqByRun.delete(runId);
+}
+
+/**
+ * Sweep stale run contexts that exceeded the given TTL.
+ * Guards against orphaned entries when lifecycle "end"/"error" events are missed.
+ */
+export function sweepStaleRunContexts(maxAgeMs = 30 * 60 * 1000): number {
+  const state = getAgentEventState();
+  const now = Date.now();
+  let swept = 0;
+  for (const [runId, ctx] of state.runContextById.entries()) {
+    // Use lastActiveAt (refreshed on every event) to avoid sweeping active runs.
+    // Fall back to registeredAt, then treat missing timestamps as infinitely old.
+    const lastSeen = ctx.lastActiveAt ?? ctx.registeredAt;
+    const age = lastSeen ? now - lastSeen : Infinity;
+    if (age > maxAgeMs) {
+      state.runContextById.delete(runId);
+      state.seqByRun.delete(runId);
+      swept++;
+    }
+  }
+  return swept;
+}
+
+export function resetAgentRunContextForTest(): void {
+  const state = getAgentEventState();
+  state.runContextById.clear();
+  state.seqByRun.clear();
+}
+
+export function emitAgentEvent(event: Omit<AgentEventPayload, "seq" | "ts">): void {
+  const state = getAgentEventState();
+  const nextSeq = (state.seqByRun.get(event.runId) ?? 0) + 1;
+  state.seqByRun.set(event.runId, nextSeq);
+  const context = state.runContextById.get(event.runId);
+  if (context) {
+    context.lastActiveAt = Date.now();
+  }
+  const isControlUiVisible = context?.isControlUiVisible ?? true;
+  const eventSessionKey =
+    typeof event.sessionKey === "string" && event.sessionKey.trim() ? event.sessionKey : undefined;
+  // Hidden channel-routed runs should not leak live assistant/tool traffic into
+  // Control UI, but lifecycle events still need the session key so gateway
+  // listeners can persist terminal session state even if run-context lookup is
+  // unavailable by the time the terminal event arrives. Terminal failures are
+  // emitted on the lifecycle stream with `phase: "error"`; the separate error
+  // stream remains redacted for hidden runs because it is observational only.
+  const preserveSessionKey = isControlUiVisible || event.stream === "lifecycle";
+  const sessionKey = preserveSessionKey ? (eventSessionKey ?? context?.sessionKey) : undefined;
+  const enriched: AgentEventPayload = {
+    runId: event.runId,
+    stream: event.stream,
+    data: event.data,
+    seq: nextSeq,
+    ts: Date.now(),
+    ...(sessionKey !== undefined ? { sessionKey } : {}),
+  };
+  notifyListeners(state.listeners, enriched);
+}
+
+export function emitAgentItemEvent(params: {
+  runId: string;
+  data: AgentItemEventData;
+  sessionKey?: string;
+}): void {
+  emitAgentEvent({
+    runId: params.runId,
+    stream: "item",
+    data: params.data as unknown as Record<string, unknown>,
+    ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+  });
+}
+
+export function emitAgentPlanEvent(params: {
+  runId: string;
+  data: AgentPlanEventData;
+  sessionKey?: string;
+}): void {
+  emitAgentEvent({
+    runId: params.runId,
+    stream: "plan",
+    data: params.data as unknown as Record<string, unknown>,
+    ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+  });
+}
+
+export function emitAgentApprovalEvent(params: {
+  runId: string;
+  data: AgentApprovalEventData;
+  sessionKey?: string;
+}): void {
+  emitAgentEvent({
+    runId: params.runId,
+    stream: "approval",
+    data: params.data as unknown as Record<string, unknown>,
+    ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+  });
+}
+
+export function emitAgentCommandOutputEvent(params: {
+  runId: string;
+  data: AgentCommandOutputEventData;
+  sessionKey?: string;
+}): void {
+  emitAgentEvent({
+    runId: params.runId,
+    stream: "command_output",
+    data: params.data as unknown as Record<string, unknown>,
+    ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+  });
+}
+
+export function emitAgentPatchSummaryEvent(params: {
+  runId: string;
+  data: AgentPatchSummaryEventData;
+  sessionKey?: string;
+}): void {
+  emitAgentEvent({
+    runId: params.runId,
+    stream: "patch",
+    data: params.data as unknown as Record<string, unknown>,
+    ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+  });
+}
+
+export function onAgentEvent(listener: (evt: AgentEventPayload) => void): () => void {
+  const state = getAgentEventState();
+  return registerListener(state.listeners, listener);
+}
+
+export function resetAgentEventsForTest(): void {
+  const state = getAgentEventState();
+  state.seqByRun.clear();
+  state.listeners.clear();
+  state.runContextById.clear();
+}

package/src/global-singleton.ts

@@ -0,0 +1,20 @@
+/**
+ * Port verbatim de `~/Desktop/GitHub/openclaw/src/shared/global-singleton.ts:1-17`.
+ *
+ * Safe for process-local caches and registries that can tolerate helper-based
+ * resolution. Do not use this for live mutable state that must survive split
+ * runtime chunks; keep those on a direct `globalThis[Symbol.for(...)]` lookup.
+ */
+export function resolveGlobalSingleton<T>(key: symbol, create: () => T): T {
+  const globalStore = globalThis as Record<PropertyKey, unknown>;
+  if (Object.prototype.hasOwnProperty.call(globalStore, key)) {
+    return globalStore[key] as T;
+  }
+  const created = create();
+  globalStore[key] = created;
+  return created;
+}
+
+export function resolveGlobalMap<TKey, TValue>(key: symbol): Map<TKey, TValue> {
+  return resolveGlobalSingleton(key, () => new Map<TKey, TValue>());
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @nubemclaw/agent-events — public surface.
+ *
+ * Re-exports the in-process bus + helpers + types from `agent-events.ts`.
+ * Consumers in this repo (`packages/cli`, `packages/gateway`,
+ * `packages/channel-telegram`, future `packages/gateway-client`) import
+ * from this entrypoint only — never reach inside `src/agent-events.ts`.
+ *
+ * The two infra helpers `resolveGlobalSingleton` and
+ * `notifyListeners`/`registerListener` are intentionally NOT re-exported:
+ * they support the bus implementation, not its public contract.
+ */
+export type {
+  AgentApprovalEventData,
+  AgentApprovalEventKind,
+  AgentApprovalEventPhase,
+  AgentApprovalEventStatus,
+  AgentCommandOutputEventData,
+  AgentEventPayload,
+  AgentEventStream,
+  AgentItemEventData,
+  AgentItemEventKind,
+  AgentItemEventPhase,
+  AgentItemEventStatus,
+  AgentPatchSummaryEventData,
+  AgentPlanEventData,
+  AgentRunContext,
+  VerboseLevel,
+} from "./agent-events.js";
+
+export {
+  clearAgentRunContext,
+  emitAgentApprovalEvent,
+  emitAgentCommandOutputEvent,
+  emitAgentEvent,
+  emitAgentItemEvent,
+  emitAgentPatchSummaryEvent,
+  emitAgentPlanEvent,
+  getAgentRunContext,
+  onAgentEvent,
+  registerAgentRunContext,
+  resetAgentEventsForTest,
+  resetAgentRunContextForTest,
+  sweepStaleRunContexts,
+} from "./agent-events.js";

package/src/listeners.ts

@@ -0,0 +1,30 @@
+/**
+ * Port verbatim de `~/Desktop/GitHub/openclaw/src/shared/listeners.ts:1-22`.
+ *
+ * `notifyListeners` swallows individual listener errors via `onError?` so a
+ * misbehaving subscriber cannot break the fan-out. `registerListener` returns
+ * an unsubscribe callback in the same shape `onAgentEvent` consumers expect.
+ */
+export function notifyListeners<T>(
+  listeners: Iterable<(event: T) => void>,
+  event: T,
+  onError?: (error: unknown) => void,
+): void {
+  for (const listener of listeners) {
+    try {
+      listener(event);
+    } catch (error) {
+      onError?.(error);
+    }
+  }
+}
+
+export function registerListener<T>(
+  listeners: Set<(event: T) => void>,
+  listener: (event: T) => void,
+): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}