laohuang 0.3.2 → 0.4.0

package/dist/events.d.ts

@@ -0,0 +1,288 @@
+/** Canonical events and the event bus used by the runtime. */
+export declare const EventKind: {
+    readonly InputUserMessage: "input.user_message";
+    /** Compatibility alias for InputUserMessage. */
+    readonly InputReceived: "input.user_message";
+    readonly InputSlashCommand: "input.slash_command";
+    readonly InputPending: "input.pending";
+    readonly InputHeld: "input.held";
+    readonly InputCancelRequested: "input.cancel_requested";
+    readonly TaskStarted: "task.started";
+    readonly TaskStateChanged: "task.state_changed";
+    readonly TaskCompleted: "task.completed";
+    readonly TaskFailed: "task.failed";
+    readonly TaskCancelled: "task.cancelled";
+    readonly ModelRequestStarted: "model.request_started";
+    readonly ModelTextDelta: "model.text_delta";
+    readonly ModelReasoningDelta: "model.reasoning_delta";
+    readonly ModelToolCallDelta: "model.tool_call_delta";
+    readonly ModelResponseValidating: "model.response_validating";
+    readonly ModelResponseCommitted: "model.response_committed";
+    readonly ModelResponseAborted: "model.response_aborted";
+    readonly ModelRequestFailed: "model.request_failed";
+    readonly ModelResponseSummary: "model.response_summary";
+    readonly ModelSwitched: "model.switched";
+    readonly AgentGuardTriggered: "agent.guard_triggered";
+    readonly AgentGuardFailed: "agent.guard_failed";
+    readonly ToolStarted: "tool.started";
+    readonly ToolOutputDelta: "tool.output_delta";
+    readonly ToolFinished: "tool.finished";
+    readonly SessionReady: "session.ready";
+    readonly SessionStopped: "session.stopped";
+    readonly UiMessage: "ui.message";
+    readonly RoutingDecided: "routing.decided";
+    /** Compatibility alias for RoutingDecided. */
+    readonly RouteDecided: "routing.decided";
+    readonly RoutingRejected: "routing.rejected";
+};
+export type EventKind = (typeof EventKind)[keyof typeof EventKind];
+export declare const EventSource: {
+    readonly User: "user";
+    readonly Cli: "cli";
+    readonly Model: "model";
+    readonly Tool: "tool";
+    readonly Session: "session";
+    readonly Router: "router";
+    readonly System: "system";
+};
+export type EventSource = (typeof EventSource)[keyof typeof EventSource];
+export declare class EventValidationError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Payload carried by an event. Every payload may gain a projection gap marker
+ * when a subscriber mailbox drops or coalesces events under backpressure.
+ */
+export interface EventPayloadBase {
+    _projection_dropped?: number;
+    [field: string]: unknown;
+}
+export interface UserMessagePayload extends EventPayloadBase {
+    content: string;
+    strategy?: string;
+}
+export interface SlashCommandPayload extends EventPayloadBase {
+    content: string;
+}
+export interface InputPendingPayload extends EventPayloadBase {
+    pending_count: number;
+}
+export interface InputHeldPayload extends EventPayloadBase {
+    held_count: number;
+}
+export interface TaskStateChangedPayload extends EventPayloadBase {
+    state: string;
+}
+export interface ModelRequestStartedPayload extends EventPayloadBase {
+    request_id: string;
+}
+export interface ModelDeltaPayload extends EventPayloadBase {
+    text: string;
+    request_id?: string;
+    coalesced_from_sequence?: number;
+}
+export interface ModelToolCallDeltaPayload extends EventPayloadBase {
+    index: number;
+    request_id?: string;
+    coalesced_from_sequence?: number;
+}
+export interface AgentGuardPayload extends EventPayloadBase {
+    reason: string;
+    tool_rounds?: number;
+    model_requests?: number;
+    total_tokens?: number;
+    elapsed_ms?: number;
+}
+export interface ToolStartedPayload extends EventPayloadBase {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface ToolOutputDeltaPayload extends EventPayloadBase {
+    stream: string;
+    text: string;
+    coalesced_from_sequence?: number;
+}
+export interface ToolFinishedPayload extends EventPayloadBase {
+    status: string;
+}
+export interface UiMessagePayload extends EventPayloadBase {
+    text: string;
+    style?: string;
+}
+export interface RoutingDecidedPayload extends EventPayloadBase {
+    destination: string;
+    reason: string;
+}
+export interface RoutingRejectedPayload extends EventPayloadBase {
+    reason: string;
+}
+export interface EventPayloadMap {
+    "input.user_message": UserMessagePayload;
+    "input.slash_command": SlashCommandPayload;
+    "input.pending": InputPendingPayload;
+    "input.held": InputHeldPayload;
+    "input.cancel_requested": EventPayloadBase;
+    "task.started": EventPayloadBase;
+    "task.state_changed": TaskStateChangedPayload;
+    "task.completed": EventPayloadBase;
+    "task.failed": EventPayloadBase;
+    "task.cancelled": EventPayloadBase;
+    "model.request_started": ModelRequestStartedPayload;
+    "model.text_delta": ModelDeltaPayload;
+    "model.reasoning_delta": ModelDeltaPayload;
+    "model.tool_call_delta": ModelToolCallDeltaPayload;
+    "model.response_validating": EventPayloadBase;
+    "model.response_committed": EventPayloadBase;
+    "model.response_aborted": EventPayloadBase;
+    "model.request_failed": EventPayloadBase;
+    "model.response_summary": EventPayloadBase;
+    "model.switched": EventPayloadBase;
+    "agent.guard_triggered": AgentGuardPayload;
+    "agent.guard_failed": AgentGuardPayload;
+    "tool.started": ToolStartedPayload;
+    "tool.output_delta": ToolOutputDeltaPayload;
+    "tool.finished": ToolFinishedPayload;
+    "session.ready": EventPayloadBase;
+    "session.stopped": EventPayloadBase;
+    "ui.message": UiMessagePayload;
+    "routing.decided": RoutingDecidedPayload;
+    "routing.rejected": RoutingRejectedPayload;
+}
+export type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
+    readonly [P in keyof T]: DeepReadonly<T[P]>;
+} : T;
+/**
+ * Immutable transport envelope.
+ *
+ * ``sequence`` is zero before publication. {@link EventBus} replaces it with
+ * a strictly increasing session-wide sequence while retaining ``event_id``.
+ */
+export interface EventEnvelope<K extends EventKind = EventKind> {
+    readonly event_id: string;
+    readonly kind: K;
+    readonly source: EventSource;
+    readonly session_id: string;
+    readonly task_id: string | null;
+    readonly correlation_id: string | null;
+    readonly sequence: number;
+    readonly payload: DeepReadonly<EventPayloadMap[K]>;
+}
+/** Discriminated union over all known event kinds. */
+export type AnyEventEnvelope = {
+    [K in EventKind]: EventEnvelope<K>;
+}[EventKind];
+export type PayloadFieldType = "string" | "integer" | "object";
+export type EventValidator = (event: AnyEventEnvelope) => boolean | void;
+export interface EventSpecOptions {
+    kind: EventKind;
+    sources?: ReadonlySet<EventSource> | null;
+    required_payload?: ReadonlySet<string>;
+    payload_types?: Readonly<Record<string, PayloadFieldType>>;
+    require_task_id?: boolean;
+    require_correlation_id?: boolean;
+    max_payload_chars?: number;
+    validator?: EventValidator | null;
+}
+/** Validation rules for a single event kind. */
+export declare class EventSpec {
+    readonly kind: EventKind;
+    readonly sources: ReadonlySet<EventSource> | null;
+    readonly required_payload: ReadonlySet<string>;
+    readonly payload_types: Readonly<Record<string, PayloadFieldType>>;
+    readonly require_task_id: boolean;
+    readonly require_correlation_id: boolean;
+    readonly max_payload_chars: number;
+    readonly validator: EventValidator | null;
+    constructor(options: EventSpecOptions);
+    validate(event: AnyEventEnvelope): void;
+}
+export declare const EVENT_SPECS: ReadonlyMap<EventKind, EventSpec>;
+export interface CreateEventOptions<K extends EventKind> {
+    source: EventSource | string;
+    session_id: string;
+    task_id?: string | null;
+    correlation_id?: string | null;
+    sequence?: number;
+    payload?: EventPayloadMap[K];
+    event_id?: string;
+}
+/** Create validated envelopes without assigning publication order. */
+export declare class EventFactory {
+    private readonly specs;
+    constructor(specs?: ReadonlyMap<EventKind, EventSpec>);
+    register(eventSpec: EventSpec): void;
+    create<K extends EventKind>(kind: K | string, options: CreateEventOptions<K>): EventEnvelope<K>;
+    validate(event: AnyEventEnvelope): void;
+}
+export interface ProjectedEvent {
+    event_id: string;
+    kind: EventKind;
+    source: EventSource;
+    session_id: string;
+    task_id: string | null;
+    correlation_id: string | null;
+    sequence: number;
+    payload: unknown;
+}
+/** Produce JSON-friendly, recursively redacted audience projections. */
+export declare class EventProjector {
+    static readonly AUDIENCES: ReadonlySet<string>;
+    project(event: AnyEventEnvelope, audience?: string): ProjectedEvent;
+}
+export type SubscriberCallback = (event: AnyEventEnvelope) => void | Promise<void>;
+export interface EventBusOptions {
+    factory?: EventFactory;
+    max_buffered_events?: number;
+    subscriber_mailbox_size?: number;
+}
+export declare class EventBufferEmptyError extends Error {
+    constructor();
+}
+export declare class EventBufferTimeoutError extends Error {
+    constructor();
+}
+/**
+ * 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 declare class EventBusClosedError extends Error {
+    constructor();
+}
+/** A FIFO bus that assigns one strict sequence across all publishers. */
+export declare class EventBus {
+    readonly factory: EventFactory;
+    private readonly maxBufferedEvents;
+    private readonly subscriberMailboxSize;
+    private readonly buffer;
+    private readonly bufferWaiters;
+    private readonly subscribers;
+    private subscriberId;
+    private sequence;
+    private closed;
+    constructor(options?: EventBusOptions);
+    get last_sequence(): number;
+    publish<K extends EventKind>(kind: K, options: Omit<CreateEventOptions<K>, "sequence" | "event_id">): EventEnvelope<K>;
+    publishEvent<K extends EventKind>(event: EventEnvelope<K>): EventEnvelope<K>;
+    /** Wait until every published event reached current subscribers. */
+    flush(): Promise<void>;
+    /** Deliver queued events and stop subscriber workers exactly once. */
+    close(): Promise<void>;
+    /**
+     * 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: SubscriberCallback): () => Promise<void>;
+    /** Pull the next buffered event, waiting up to ``timeoutMs`` if given. */
+    get(timeoutMs?: number): Promise<AnyEventEnvelope>;
+    getNowait(): AnyEventEnvelope;
+    drain(limit?: number): AnyEventEnvelope[];
+    qsize(): number;
+    private feedBufferWaiters;
+}