laohuang 0.3.2 → 0.4.1

package/dist/events.js

@@ -0,0 +1,838 @@
+/** Canonical events and the event bus used by the runtime. */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+export const EventKind = {
+    InputUserMessage: "input.user_message",
+    /** Compatibility alias for InputUserMessage. */
+    InputReceived: "input.user_message",
+    InputSlashCommand: "input.slash_command",
+    InputPending: "input.pending",
+    InputHeld: "input.held",
+    InputCancelRequested: "input.cancel_requested",
+    TaskStarted: "task.started",
+    TaskStateChanged: "task.state_changed",
+    TaskCompleted: "task.completed",
+    TaskFailed: "task.failed",
+    TaskCancelled: "task.cancelled",
+    ModelRequestStarted: "model.request_started",
+    ModelTextDelta: "model.text_delta",
+    ModelReasoningDelta: "model.reasoning_delta",
+    ModelToolCallDelta: "model.tool_call_delta",
+    ModelResponseValidating: "model.response_validating",
+    ModelResponseCommitted: "model.response_committed",
+    ModelResponseAborted: "model.response_aborted",
+    ModelRequestFailed: "model.request_failed",
+    ModelResponseSummary: "model.response_summary",
+    ModelSwitched: "model.switched",
+    AgentGuardTriggered: "agent.guard_triggered",
+    AgentGuardFailed: "agent.guard_failed",
+    ToolStarted: "tool.started",
+    ToolOutputDelta: "tool.output_delta",
+    ToolFinished: "tool.finished",
+    SessionReady: "session.ready",
+    SessionStopped: "session.stopped",
+    UiMessage: "ui.message",
+    RoutingDecided: "routing.decided",
+    /** Compatibility alias for RoutingDecided. */
+    RouteDecided: "routing.decided",
+    RoutingRejected: "routing.rejected",
+};
+const EVENT_KIND_VALUES = new Set(Object.values(EventKind));
+export const EventSource = {
+    User: "user",
+    Cli: "cli",
+    Model: "model",
+    Tool: "tool",
+    Session: "session",
+    Router: "router",
+    System: "system",
+};
+const EVENT_SOURCE_VALUES = new Set(Object.values(EventSource));
+export class EventValidationError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "EventValidationError";
+    }
+}
+/** Deep-copy containers into deeply frozen ones, like Python's ``_freeze``. */
+function freezeValue(value) {
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map((item) => freezeValue(item)));
+    }
+    if (value !== null && typeof value === "object") {
+        if (value instanceof Map || value instanceof Set) {
+            return Object.freeze(value);
+        }
+        const copy = {};
+        for (const [key, item] of Object.entries(value)) {
+            copy[key] = freezeValue(item);
+        }
+        return Object.freeze(copy);
+    }
+    return value;
+}
+function gapOf(payload) {
+    const value = payload["_projection_dropped"];
+    return typeof value === "number" && value > 0 ? value : 0;
+}
+const DEFAULT_MAX_PAYLOAD_CHARS = 1_000_000;
+function payloadFieldMatches(value, expected) {
+    switch (expected) {
+        case "string":
+            return typeof value === "string";
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "object":
+            return value !== null && typeof value === "object" && !Array.isArray(value);
+    }
+}
+/** Validation rules for a single event kind. */
+export class EventSpec {
+    kind;
+    sources;
+    required_payload;
+    payload_types;
+    require_task_id;
+    require_correlation_id;
+    max_payload_chars;
+    validator;
+    constructor(options) {
+        this.kind = options.kind;
+        this.sources = options.sources ?? null;
+        this.required_payload = options.required_payload ?? new Set();
+        this.payload_types = options.payload_types ?? {};
+        this.require_task_id = options.require_task_id ?? false;
+        this.require_correlation_id = options.require_correlation_id ?? false;
+        this.max_payload_chars =
+            options.max_payload_chars ?? DEFAULT_MAX_PAYLOAD_CHARS;
+        this.validator = options.validator ?? null;
+    }
+    validate(event) {
+        if (event.kind !== this.kind) {
+            throw new EventValidationError(`expected event kind ${this.kind}, got ${event.kind}`);
+        }
+        if (this.sources !== null && !this.sources.has(event.source)) {
+            throw new EventValidationError(`source ${event.source} is not valid for ${event.kind}`);
+        }
+        if (this.require_task_id && !event.task_id) {
+            throw new EventValidationError(`event ${event.kind} requires task_id`);
+        }
+        if (this.require_correlation_id && !event.correlation_id) {
+            throw new EventValidationError(`event ${event.kind} requires correlation_id`);
+        }
+        const payload = event.payload;
+        const missing = [...this.required_payload]
+            .filter((name) => !(name in payload))
+            .sort();
+        if (missing.length > 0) {
+            throw new EventValidationError(`event ${event.kind} is missing payload fields: ${missing.join(", ")}`);
+        }
+        for (const [name, expected] of Object.entries(this.payload_types)) {
+            if (name in payload && !payloadFieldMatches(payload[name], expected)) {
+                throw new EventValidationError(`event ${event.kind} payload field '${name}' has invalid type`);
+            }
+        }
+        let payloadSize;
+        try {
+            payloadSize = JSON.stringify(payload).length;
+        }
+        catch (error) {
+            throw new EventValidationError(`event ${event.kind} payload must be JSON-compatible`, { cause: error });
+        }
+        if (payloadSize > this.max_payload_chars) {
+            throw new EventValidationError(`event ${event.kind} payload exceeds ${this.max_payload_chars} characters`);
+        }
+        if (this.validator !== null && this.validator(event) === false) {
+            throw new EventValidationError(`custom validation failed for ${event.kind}`);
+        }
+    }
+}
+function spec(kind, init) {
+    return new EventSpec({
+        kind,
+        sources: new Set(init.sources),
+        required_payload: new Set(init.required_payload),
+        payload_types: init.payload_types,
+        require_task_id: init.require_task_id,
+        require_correlation_id: init.require_correlation_id,
+        max_payload_chars: init.max_payload_chars,
+    });
+}
+function taskLifecycleSpec(kind) {
+    return spec(kind, { sources: [EventSource.Session], require_task_id: true });
+}
+function modelEventSpec(kind, delta) {
+    return spec(kind, {
+        sources: [EventSource.Model],
+        require_task_id: true,
+        require_correlation_id: true,
+        max_payload_chars: delta ? 16_384 : 100_000,
+    });
+}
+function toolEventSpec(kind) {
+    return spec(kind, {
+        sources: [EventSource.Tool],
+        require_task_id: true,
+        require_correlation_id: true,
+        max_payload_chars: 100_000,
+    });
+}
+// The default boundary prevents external/user events from impersonating model,
+// tool, router, and lifecycle callbacks. Integrations may add stricter payload
+// specs through EventFactory.register without changing the envelope protocol.
+export const EVENT_SPECS = new Map([
+    spec(EventKind.InputUserMessage, {
+        sources: [EventSource.User, EventSource.Cli],
+        required_payload: ["content"],
+        payload_types: { content: "string", strategy: "string" },
+        max_payload_chars: 100_000,
+    }),
+    spec(EventKind.InputSlashCommand, {
+        sources: [EventSource.User, EventSource.Cli],
+        required_payload: ["content"],
+        payload_types: { content: "string" },
+        max_payload_chars: 16_384,
+    }),
+    spec(EventKind.InputPending, {
+        sources: [EventSource.Session],
+        required_payload: ["pending_count"],
+        payload_types: { pending_count: "integer" },
+        require_task_id: true,
+        require_correlation_id: true,
+    }),
+    spec(EventKind.InputHeld, {
+        sources: [EventSource.Session],
+        required_payload: ["held_count"],
+        payload_types: { held_count: "integer" },
+        require_task_id: true,
+        require_correlation_id: true,
+    }),
+    spec(EventKind.InputCancelRequested, {
+        sources: [EventSource.User, EventSource.Cli, EventSource.Session],
+    }),
+    taskLifecycleSpec(EventKind.TaskStarted),
+    spec(EventKind.TaskStateChanged, {
+        sources: [EventSource.Session],
+        required_payload: ["state"],
+        payload_types: { state: "string" },
+        require_task_id: true,
+    }),
+    taskLifecycleSpec(EventKind.TaskCompleted),
+    taskLifecycleSpec(EventKind.TaskFailed),
+    taskLifecycleSpec(EventKind.TaskCancelled),
+    spec(EventKind.SessionReady, { sources: [EventSource.Session] }),
+    spec(EventKind.SessionStopped, { sources: [EventSource.Session] }),
+    spec(EventKind.ModelRequestStarted, {
+        sources: [EventSource.Model],
+        required_payload: ["request_id"],
+        payload_types: { request_id: "string" },
+        require_task_id: true,
+        require_correlation_id: true,
+        max_payload_chars: 100_000,
+    }),
+    spec(EventKind.ModelTextDelta, {
+        sources: [EventSource.Model],
+        required_payload: ["text"],
+        payload_types: { text: "string", request_id: "string" },
+        require_task_id: true,
+        require_correlation_id: true,
+        max_payload_chars: 16_384,
+    }),
+    spec(EventKind.ModelReasoningDelta, {
+        sources: [EventSource.Model],
+        required_payload: ["text"],
+        payload_types: { text: "string", request_id: "string" },
+        require_task_id: true,
+        require_correlation_id: true,
+        max_payload_chars: 16_384,
+    }),
+    spec(EventKind.ModelToolCallDelta, {
+        sources: [EventSource.Model],
+        required_payload: ["index"],
+        payload_types: { index: "integer", request_id: "string" },
+        require_task_id: true,
+        require_correlation_id: true,
+        max_payload_chars: 16_384,
+    }),
+    modelEventSpec(EventKind.ModelResponseValidating, false),
+    modelEventSpec(EventKind.ModelResponseCommitted, false),
+    modelEventSpec(EventKind.ModelResponseAborted, false),
+    modelEventSpec(EventKind.ModelRequestFailed, false),
+    modelEventSpec(EventKind.ModelResponseSummary, false),
+    spec(EventKind.ModelSwitched, {
+        sources: [EventSource.Model, EventSource.Session, EventSource.System],
+    }),
+    spec(EventKind.AgentGuardTriggered, {
+        sources: [EventSource.System],
+        required_payload: ["reason"],
+        payload_types: {
+            reason: "string",
+            tool_rounds: "integer",
+            model_requests: "integer",
+            total_tokens: "integer",
+            elapsed_ms: "integer",
+        },
+        require_task_id: true,
+        max_payload_chars: 100_000,
+    }),
+    spec(EventKind.AgentGuardFailed, {
+        sources: [EventSource.System],
+        required_payload: ["reason"],
+        payload_types: {
+            reason: "string",
+            tool_rounds: "integer",
+            model_requests: "integer",
+            total_tokens: "integer",
+            elapsed_ms: "integer",
+        },
+        require_task_id: true,
+        max_payload_chars: 100_000,
+    }),
+    spec(EventKind.UiMessage, {
+        sources: [EventSource.Cli, EventSource.Session, EventSource.System],
+        required_payload: ["text"],
+        payload_types: { text: "string", style: "string" },
+        max_payload_chars: 100_000,
+    }),
+    spec(EventKind.ToolStarted, {
+        sources: [EventSource.Tool],
+        required_payload: ["name", "arguments"],
+        payload_types: { name: "string", arguments: "object" },
+        require_task_id: true,
+        require_correlation_id: true,
+        max_payload_chars: 100_000,
+    }),
+    spec(EventKind.ToolOutputDelta, {
+        sources: [EventSource.Tool],
+        required_payload: ["stream", "text"],
+        payload_types: { stream: "string", text: "string" },
+        require_task_id: true,
+        require_correlation_id: true,
+        max_payload_chars: 16_384,
+    }),
+    spec(EventKind.ToolFinished, {
+        sources: [EventSource.Tool],
+        required_payload: ["status"],
+        payload_types: { status: "string" },
+        require_task_id: true,
+        require_correlation_id: true,
+        max_payload_chars: 100_000,
+    }),
+    spec(EventKind.RoutingDecided, {
+        sources: [EventSource.Router],
+        required_payload: ["destination", "reason"],
+        payload_types: { destination: "string", reason: "string" },
+        require_correlation_id: true,
+    }),
+    spec(EventKind.RoutingRejected, {
+        sources: [EventSource.Router],
+        required_payload: ["reason"],
+        payload_types: { reason: "string" },
+        require_correlation_id: true,
+    }),
+].map((eventSpec) => [eventSpec.kind, eventSpec]));
+/** Create validated envelopes without assigning publication order. */
+export class EventFactory {
+    specs;
+    constructor(specs) {
+        this.specs = new Map(specs ?? EVENT_SPECS);
+    }
+    register(eventSpec) {
+        this.specs.set(eventSpec.kind, eventSpec);
+    }
+    create(kind, options) {
+        if (!EVENT_KIND_VALUES.has(kind) && !this.specs.has(kind)) {
+            throw new EventValidationError(`'${String(kind)}' is not a valid EventKind`);
+        }
+        if (!EVENT_SOURCE_VALUES.has(options.source)) {
+            throw new EventValidationError(`'${String(options.source)}' is not a valid EventSource`);
+        }
+        const eventKind = kind;
+        const eventSource = options.source;
+        const eventId = options.event_id ?? randomUUID().replaceAll("-", "");
+        const sessionId = options.session_id;
+        const sequence = options.sequence ?? 0;
+        if (!eventId) {
+            throw new EventValidationError("event_id must not be empty");
+        }
+        if (!sessionId) {
+            throw new EventValidationError("session_id must not be empty");
+        }
+        if (sequence < 0) {
+            throw new EventValidationError("sequence must be non-negative");
+        }
+        const envelope = {
+            event_id: eventId,
+            kind: eventKind,
+            source: eventSource,
+            session_id: sessionId,
+            task_id: options.task_id ?? null,
+            correlation_id: options.correlation_id ?? null,
+            sequence,
+            payload: freezeValue(options.payload ?? {}),
+        };
+        const eventSpec = this.specs.get(eventKind);
+        if (eventSpec !== undefined) {
+            eventSpec.validate(envelope);
+        }
+        return envelope;
+    }
+    validate(event) {
+        const eventSpec = this.specs.get(event.kind);
+        if (eventSpec !== undefined) {
+            eventSpec.validate(event);
+        }
+    }
+}
+const SENSITIVE_FIELDS = new Set([
+    "api_key",
+    "apikey",
+    "authorization",
+    "token",
+    "access_token",
+    "refresh_token",
+    "secret",
+    "password",
+]);
+const SENSITIVE_TEXT_PATTERNS = [
+    /(authorization\s*:\s*bearer\s+)[^\s'"]+/gi,
+    /(\b(?:api[_-]?key|access[_-]?token|token|password|secret)\s*[:=]\s*)[^\s'"]+/gi,
+];
+function projectValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => projectValue(item));
+    }
+    if (value !== null && typeof value === "object") {
+        const projected = {};
+        for (const [key, item] of Object.entries(value)) {
+            const normalized = key.toLowerCase().replaceAll("-", "_");
+            if (SENSITIVE_FIELDS.has(normalized) || normalized.endsWith("_secret")) {
+                projected[key] = "[REDACTED]";
+            }
+            else {
+                projected[key] = projectValue(item);
+            }
+        }
+        return projected;
+    }
+    if (typeof value === "string") {
+        let projected = value;
+        for (const pattern of SENSITIVE_TEXT_PATTERNS) {
+            projected = projected.replace(pattern, "$1[REDACTED]");
+        }
+        return projected;
+    }
+    return value;
+}
+/** Produce JSON-friendly, recursively redacted audience projections. */
+export class EventProjector {
+    static AUDIENCES = new Set([
+        "terminal",
+        "web",
+        "log",
+        "router",
+    ]);
+    project(event, audience = "terminal") {
+        if (!EventProjector.AUDIENCES.has(audience)) {
+            throw new Error(`unknown event audience: ${audience}`);
+        }
+        return {
+            event_id: event.event_id,
+            kind: event.kind,
+            source: event.source,
+            session_id: event.session_id,
+            task_id: event.task_id,
+            correlation_id: event.correlation_id,
+            sequence: event.sequence,
+            payload: projectValue(event.payload),
+        };
+    }
+}
+const COALESCIBLE_EVENTS = new Set([
+    EventKind.ModelTextDelta,
+    EventKind.ModelReasoningDelta,
+    EventKind.ModelToolCallDelta,
+    EventKind.ToolOutputDelta,
+]);
+const MAX_COALESCED_TEXT_CHARS = 65_536;
+// Reserved headroom so control/lifecycle events always fit in a mailbox even
+// when display-only deltas flood it.
+const MAILBOX_CRITICAL_HEADROOM = 64;
+function withPayload(event, payload) {
+    return {
+        ...event,
+        payload: freezeValue(payload),
+    };
+}
+/**
+ * One bounded queue per subscriber, drained by a promise loop.
+ *
+ * A slow terminal or web projection can no longer stall another subscriber.
+ * Under pressure only adjacent compatible deltas are combined; lifecycle and
+ * control events are never discarded.
+ */
+/**
+ * Identifies the mailbox whose callback is currently executing, the
+ * single-threaded analogue of Python's ``self._worker is current_thread()``
+ * self-join guard in ``_SubscriberMailbox.close``.
+ */
+const subscriberCallbackContext = new AsyncLocalStorage();
+class SubscriberMailbox {
+    callback;
+    maxItems;
+    items = [];
+    unfinished = 0;
+    dropped = 0;
+    pendingGap = 0;
+    closed = false;
+    wakeWaiters = [];
+    flushWaiters = [];
+    workerDone;
+    constructor(callback, maxItems) {
+        this.callback = callback;
+        this.maxItems = maxItems;
+        this.workerDone = this.run();
+    }
+    static merge(left, right) {
+        if (left.kind !== right.kind ||
+            left.task_id !== right.task_id ||
+            left.correlation_id !== right.correlation_id ||
+            !COALESCIBLE_EVENTS.has(left.kind)) {
+            return null;
+        }
+        const leftText = left.payload["text"];
+        const rightText = right.payload["text"];
+        if (typeof leftText !== "string" || typeof rightText !== "string") {
+            return null;
+        }
+        if (leftText.length + rightText.length > MAX_COALESCED_TEXT_CHARS) {
+            return null;
+        }
+        const payload = { ...right.payload };
+        payload["text"] = leftText + rightText;
+        const inheritedGap = gapOf(left.payload);
+        if (inheritedGap > 0) {
+            payload["_projection_dropped"] = gapOf(right.payload) + inheritedGap;
+        }
+        payload["coalesced_from_sequence"] =
+            left.payload["coalesced_from_sequence"] ?? left.sequence;
+        return withPayload(right, payload);
+    }
+    enqueue(event) {
+        if (this.closed) {
+            return false;
+        }
+        if (this.items.length > 0) {
+            const last = this.items[this.items.length - 1];
+            const merged = SubscriberMailbox.merge(last, event);
+            if (merged !== null &&
+                this.items.length >= this.maxItems - MAILBOX_CRITICAL_HEADROOM) {
+                this.items[this.items.length - 1] = this.withGapMarker(merged);
+                return true;
+            }
+        }
+        if (COALESCIBLE_EVENTS.has(event.kind) &&
+            this.items.length >= this.maxItems - MAILBOX_CRITICAL_HEADROOM) {
+            this.recordDrop();
+            return false;
+        }
+        if (this.items.length >= this.maxItems) {
+            // Preserve control/lifecycle events by evicting an older display-only
+            // delta. If a subscriber cannot consume even the reserved critical
+            // capacity, detach at this projection boundary instead of blocking the
+            // runtime and cancellation.
+            let droppedIndex = this.items.findIndex((queued) => COALESCIBLE_EVENTS.has(queued.kind));
+            if (droppedIndex === -1) {
+                droppedIndex = 0;
+            }
+            const droppedEvent = this.items[droppedIndex];
+            this.items.splice(droppedIndex, 1);
+            this.unfinished -= 1;
+            this.recordDrop(1 + gapOf(droppedEvent.payload));
+        }
+        this.items.push(this.withGapMarker(event));
+        this.unfinished += 1;
+        this.wake();
+        return true;
+    }
+    recordDrop(count = 1) {
+        this.dropped += count;
+        this.pendingGap += count;
+    }
+    withGapMarker(event) {
+        if (this.pendingGap === 0) {
+            return event;
+        }
+        const payload = { ...event.payload };
+        payload["_projection_dropped"] = gapOf(payload) + this.pendingGap;
+        this.pendingGap = 0;
+        return withPayload(event, payload);
+    }
+    async flush(timeoutMs) {
+        const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+        while (this.unfinished > 0) {
+            if (deadline === undefined) {
+                await new Promise((resolve) => {
+                    this.flushWaiters.push(resolve);
+                });
+                continue;
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                return false;
+            }
+            const waiter = new Promise((resolve) => {
+                this.flushWaiters.push(resolve);
+            });
+            let timer;
+            const timeout = new Promise((resolve) => {
+                timer = setTimeout(resolve, remaining);
+            });
+            await Promise.race([waiter, timeout]);
+            clearTimeout(timer);
+        }
+        return true;
+    }
+    async close() {
+        if (subscriberCallbackContext.getStore() === this) {
+            // Self-join guard: closing from inside the subscriber callback must
+            // not flush or await the worker — the worker is this very call stack,
+            // so waiting here would deadlock. Remaining items are still drained
+            // by the worker before it exits, as in the Python original.
+            this.closed = true;
+            this.wake();
+            this.notifyFlushWaiters();
+            return;
+        }
+        const drained = await this.flush(2000);
+        this.closed = true;
+        if (!drained) {
+            const queued = this.items.length;
+            this.items = [];
+            this.unfinished -= queued;
+            this.recordDrop(queued);
+        }
+        this.wake();
+        this.notifyFlushWaiters();
+        await this.workerDone;
+    }
+    wake() {
+        const waiters = this.wakeWaiters;
+        this.wakeWaiters = [];
+        for (const resolve of waiters) {
+            resolve();
+        }
+    }
+    notifyFlushWaiters() {
+        const waiters = this.flushWaiters;
+        this.flushWaiters = [];
+        for (const resolve of waiters) {
+            resolve();
+        }
+    }
+    async run() {
+        for (;;) {
+            while (this.items.length === 0 && !this.closed) {
+                await new Promise((resolve) => {
+                    this.wakeWaiters.push(resolve);
+                });
+            }
+            if (this.items.length === 0 && this.closed) {
+                return;
+            }
+            const event = this.items.shift();
+            try {
+                await subscriberCallbackContext.run(this, () => this.callback(event));
+            }
+            catch {
+                // A broken projection is isolated to its own mailbox.
+            }
+            finally {
+                this.unfinished -= 1;
+                this.notifyFlushWaiters();
+            }
+        }
+    }
+}
+export class EventBufferEmptyError extends Error {
+    constructor() {
+        super("no buffered events");
+        this.name = "EventBufferEmptyError";
+    }
+}
+export class EventBufferTimeoutError extends Error {
+    constructor() {
+        super("timed out waiting for a buffered event");
+        this.name = "EventBufferTimeoutError";
+    }
+}
+/**
+ * Thrown by publish/subscribe and used to reject pending pull waiters once
+ * the bus has been closed, so consumers can detect shutdown via `instanceof`
+ * instead of matching the message.
+ */
+export class EventBusClosedError extends Error {
+    constructor() {
+        super("event bus is closed");
+        this.name = "EventBusClosedError";
+    }
+}
+/** A FIFO bus that assigns one strict sequence across all publishers. */
+export class EventBus {
+    factory;
+    maxBufferedEvents;
+    subscriberMailboxSize;
+    buffer = [];
+    bufferWaiters = [];
+    subscribers = new Map();
+    subscriberId = 0;
+    sequence = 0;
+    closed = false;
+    constructor(options = {}) {
+        const maxBufferedEvents = options.max_buffered_events ?? 4_096;
+        if (maxBufferedEvents <= 0) {
+            throw new RangeError("max_buffered_events must be positive");
+        }
+        const subscriberMailboxSize = options.subscriber_mailbox_size ?? 4_096;
+        if (subscriberMailboxSize <= MAILBOX_CRITICAL_HEADROOM) {
+            throw new RangeError("subscriber_mailbox_size must be greater than 64");
+        }
+        this.factory = options.factory ?? new EventFactory();
+        this.maxBufferedEvents = maxBufferedEvents;
+        this.subscriberMailboxSize = subscriberMailboxSize;
+    }
+    get last_sequence() {
+        return this.sequence;
+    }
+    publish(kind, options) {
+        const event = this.factory.create(kind, options);
+        return this.publishEvent(event);
+    }
+    publishEvent(event) {
+        this.factory.validate(event);
+        if (this.closed) {
+            throw new EventBusClosedError();
+        }
+        this.sequence += 1;
+        const published = { ...event, sequence: this.sequence };
+        if (this.buffer.length >= this.maxBufferedEvents) {
+            // Subscriber mailboxes retain/coalesce independently. The pull buffer
+            // is bounded so an unused diagnostic queue cannot grow forever during
+            // long Bash/model streams.
+            this.buffer.shift();
+        }
+        this.buffer.push(published);
+        this.feedBufferWaiters();
+        for (const mailbox of this.subscribers.values()) {
+            mailbox.enqueue(published);
+        }
+        return published;
+    }
+    /** Wait until every published event reached current subscribers. */
+    async flush() {
+        for (;;) {
+            const before = this.sequence;
+            for (const mailbox of [...this.subscribers.values()]) {
+                await mailbox.flush();
+            }
+            if (this.sequence === before) {
+                return;
+            }
+        }
+    }
+    /** Deliver queued events and stop subscriber workers exactly once. */
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        const mailboxes = [...this.subscribers.values()];
+        this.subscribers.clear();
+        await Promise.all(mailboxes.map((mailbox) => mailbox.close()));
+        for (const waiter of this.bufferWaiters.splice(0)) {
+            if (waiter.timer !== undefined) {
+                clearTimeout(waiter.timer);
+            }
+            waiter.reject(new EventBusClosedError());
+        }
+    }
+    /**
+     * Fan out every future event and return an unsubscribe callback.
+     *
+     * The returned callback detaches the subscriber immediately and resolves
+     * only after the mailbox drained, so once it returns no further events
+     * can be delivered to that callback (matching Python's blocking
+     * ``unsubscribe``).
+     */
+    subscribe(callback) {
+        if (this.closed) {
+            throw new EventBusClosedError();
+        }
+        this.subscriberId += 1;
+        const id = this.subscriberId;
+        const mailbox = new SubscriberMailbox(callback, this.subscriberMailboxSize);
+        this.subscribers.set(id, mailbox);
+        return async () => {
+            const removed = this.subscribers.get(id);
+            if (removed !== undefined) {
+                this.subscribers.delete(id);
+                await removed.close();
+            }
+        };
+    }
+    /** Pull the next buffered event, waiting up to ``timeoutMs`` if given. */
+    get(timeoutMs) {
+        const buffered = this.buffer.shift();
+        if (buffered !== undefined) {
+            return Promise.resolve(buffered);
+        }
+        if (this.closed) {
+            return Promise.reject(new EventBusClosedError());
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject };
+            if (timeoutMs !== undefined) {
+                waiter.timer = setTimeout(() => {
+                    const index = this.bufferWaiters.indexOf(waiter);
+                    if (index !== -1) {
+                        this.bufferWaiters.splice(index, 1);
+                    }
+                    reject(new EventBufferTimeoutError());
+                }, timeoutMs);
+            }
+            this.bufferWaiters.push(waiter);
+        });
+    }
+    getNowait() {
+        const buffered = this.buffer.shift();
+        if (buffered === undefined) {
+            throw new EventBufferEmptyError();
+        }
+        return buffered;
+    }
+    drain(limit) {
+        const events = [];
+        while (limit === undefined || events.length < limit) {
+            const buffered = this.buffer.shift();
+            if (buffered === undefined) {
+                break;
+            }
+            events.push(buffered);
+        }
+        return events;
+    }
+    qsize() {
+        return this.buffer.length;
+    }
+    feedBufferWaiters() {
+        while (this.bufferWaiters.length > 0 && this.buffer.length > 0) {
+            const waiter = this.bufferWaiters.shift();
+            const event = this.buffer.shift();
+            if (waiter.timer !== undefined) {
+                clearTimeout(waiter.timer);
+            }
+            waiter.resolve(event);
+        }
+    }
+}
+//# sourceMappingURL=events.js.map