@obora/runtime 0.1.0

package/dist/blackboard/events/event-bus.d.ts

@@ -0,0 +1,254 @@
+/**
+ * @module events/event-bus
+ * @description Event Bus 구현 - Pub/Sub 패턴, 와일드카드 구독, 이벤트 필터링 지원
+ */
+import type { Event, EventType, EventByType, EventCategory } from "./types";
+import type { AgentId } from "../types";
+/**
+ * 이벤트 핸들러 타입
+ */
+export type EventHandler<T extends Event = Event> = (event: T) => void | Promise<void>;
+/**
+ * 구독 해제 함수
+ */
+export type Unsubscribe = () => void;
+/**
+ * 이벤트 필터 조건
+ */
+export interface EventFilter {
+    /** 소스 에이전트 ID */
+    source?: AgentId | "system";
+    /** 상관 ID */
+    correlationId?: string;
+    /** 커스텀 필터 함수 */
+    predicate?: (event: Event) => boolean;
+}
+/**
+ * Event Bus 설정
+ */
+export interface EventBusOptions {
+    /** 최대 리스너 수 (기본: 100) */
+    maxListeners?: number;
+    /** 비동기 핸들러 에러 시 throw 여부 (기본: false) */
+    throwOnAsyncError?: boolean;
+    /** 비동기 핸들러 에러 시 에러 이벤트 발행 여부 (기본: true) */
+    emitErrorEvent?: boolean;
+    /** 이벤트 히스토리 유지 개수 (기본: 0 = 유지 안함) */
+    historySize?: number;
+    /** 디버그 모드 */
+    debug?: boolean;
+}
+/**
+ * Event Bus 통계
+ */
+export interface EventBusStats {
+    /** 총 발행된 이벤트 수 */
+    totalEmitted: number;
+    /** 타입별 발행 수 */
+    emittedByType: Map<string, number>;
+    /** 현재 구독자 수 */
+    subscriberCount: number;
+    /** 타입별 구독자 수 */
+    subscribersByType: Map<string, number>;
+}
+/**
+ * 이벤트 대기용 타임아웃 에러
+ */
+export declare class EventTimeoutError extends Error {
+    constructor(eventType: string, timeout: number);
+}
+/**
+ * Event Bus
+ * @description Blackboard 이벤트를 위한 Pub/Sub 시스템
+ * @description EventEmitter 상속하지 않고 자체 구현 (브라우저 호환)
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus({ historySize: 100 });
+ *
+ * // 특정 이벤트 구독
+ * const unsub = bus.subscribe('task.completed', (event) => {
+ *   console.log('Task completed:', event.payload.taskId);
+ * });
+ *
+ * // 와일드카드 구독
+ * bus.subscribe('task.*', (event) => {
+ *   console.log('Task event:', event.type);
+ * });
+ *
+ * // 모든 이벤트 구독
+ * bus.subscribe('*', (event) => {
+ *   console.log('Any event:', event.type);
+ * });
+ *
+ * // 필터와 함께 구독
+ * bus.subscribeWithFilter('decision.*',
+ *   { source: createAgentId('ceo') },
+ *   (event) => console.log('CEO decision event')
+ * );
+ *
+ * // 이벤트 발행
+ * bus.emit({
+ *   id: generateId(),
+ *   type: 'task.completed',
+ *   timestamp: new Date(),
+ *   source: 'system',
+ *   payload: { taskId: createTaskId('task-1'), result: {}, duration: 5000 }
+ * });
+ *
+ * // 구독 해제
+ * unsub();
+ * ```
+ */
+export declare class EventBus {
+    private readonly options;
+    private history;
+    private stats;
+    private subscriptions;
+    private nextSubscriptionId;
+    /** 에러 이벤트 발행 중인지 체크 (재귀 방지) */
+    private isEmittingError;
+    constructor(options?: EventBusOptions);
+    /**
+     * 이벤트 구독
+     * @param eventType - 이벤트 타입 (와일드카드 지원: 'task.*', '*')
+     * @param handler - 이벤트 핸들러
+     * @returns 구독 해제 함수
+     */
+    subscribe<T extends EventType>(eventType: T | `${EventCategory}.*` | "*", handler: EventHandler<EventByType<T>>): Unsubscribe;
+    /**
+     * 필터와 함께 구독
+     * @param eventType - 이벤트 타입
+     * @param filter - 필터 조건
+     * @param handler - 이벤트 핸들러
+     * @returns 구독 해제 함수
+     */
+    subscribeWithFilter<T extends EventType>(eventType: T | `${EventCategory}.*` | "*", filter: EventFilter, handler: EventHandler<EventByType<T>>): Unsubscribe;
+    /**
+     * 일회성 구독
+     * @param eventType - 이벤트 타입
+     * @param handler - 이벤트 핸들러
+     * @returns 구독 해제 함수
+     */
+    subscribeOnce<T extends EventType>(eventType: T, handler: EventHandler<EventByType<T>>): Unsubscribe;
+    /**
+     * 구독 해제
+     * @param eventType - 이벤트 타입
+     * @param handler - 제거할 핸들러
+     */
+    unsubscribe<T extends EventType>(eventType: T | `${EventCategory}.*` | "*", handler: EventHandler<EventByType<T>>): void;
+    /**
+     * 모든 구독 해제
+     * @param eventType - 특정 이벤트 타입만 해제 (선택)
+     */
+    unsubscribeAll<T extends EventType>(eventType?: T | `${EventCategory}.*` | "*"): void;
+    /**
+     * 이벤트 버스 초기화 (히스토리만 지움, 구독자는 유지)
+     */
+    clear(): void;
+    /**
+     * 이벤트 발행
+     * @param event - 발행할 이벤트
+     */
+    emit<T extends Event>(event: T): void;
+    /**
+     * 이벤트 발행 (비동기 핸들러 완료 대기)
+     * @param event - 발행할 이벤트
+     * @returns 모든 핸들러 완료 시 resolve
+     */
+    emitAsync<T extends Event>(event: T): Promise<void>;
+    /**
+     * 배치 이벤트 발행
+     * @param events - 발행할 이벤트 목록
+     */
+    emitBatch(events: Event[]): void;
+    /**
+     * 이벤트 히스토리 조회
+     * @param filter - 필터 조건
+     * @param limit - 최대 개수
+     * @returns 필터링된 이벤트 목록
+     */
+    getHistory(filter?: {
+        type?: EventType | `${EventCategory}.*`;
+        source?: AgentId | "system";
+        since?: Date;
+        until?: Date;
+        limit?: number;
+    }, limitArg?: number): Event[];
+    /**
+     * 히스토리 재생
+     * @description 지정된 이벤트들을 다시 발행
+     * @param events - 재생할 이벤트 목록
+     */
+    replay(events: Event[]): void;
+    /**
+     * 히스토리 클리어
+     */
+    clearHistory(): void;
+    /**
+     * 통계 조회
+     */
+    getStats(): Readonly<EventBusStats> & {
+        eventsByType: Record<string, number>;
+    };
+    /**
+     * 모든 구독 해제
+     */
+    removeAllSubscribers(): void;
+    /**
+     * 특정 타입의 모든 구독 해제
+     */
+    removeSubscribersForType(eventType: EventType | `${EventCategory}.*` | "*"): void;
+    /**
+     * 이벤트 대기 (Promise 기반)
+     * @param eventType - 대기할 이벤트 타입
+     * @param timeout - 타임아웃 (ms)
+     * @returns 발생한 이벤트
+     */
+    waitFor<T extends EventType>(eventType: T, timeout?: number, predicate?: (event: EventByType<T>) => boolean): Promise<EventByType<T>>;
+    /**
+     * 이벤트 대기 (조건 충족 시)
+     * @param eventType - 대기할 이벤트 타입
+     * @param predicate - 조건 함수
+     * @param timeout - 타임아웃 (ms)
+     */
+    waitForCondition<T extends EventType>(eventType: T, predicate: (event: EventByType<T>) => boolean, timeout?: number): Promise<EventByType<T>>;
+    /**
+     * 에러 이벤트 발행
+     * @description 핸들러 에러 발생 시 시스템 에러 이벤트 발행
+     * @private
+     */
+    private emitError;
+    /**
+     * 와일드카드 패턴 매칭
+     * @param pattern - 패턴 (예: 'task.*')
+     * @param eventType - 실제 이벤트 타입
+     */
+    private matchesPattern;
+    /**
+     * 필터 적용
+     * @param event - 이벤트
+     * @param filter - 필터 조건
+     */
+    private applyFilter;
+    /**
+     * 히스토리에 이벤트 추가
+     */
+    private addToHistory;
+    /**
+     * 통계 업데이트
+     */
+    private updateStats;
+    /**
+     * 구독자 통계 업데이트
+     */
+    private updateSubscriberStats;
+    /**
+     * 초기 통계 생성
+     */
+    private createInitialStats;
+    /**
+     * 디버그 로그
+     */
+    private debugLog;
+}

package/dist/blackboard/events/event-factory.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @module events/event-factory
+ * @description 이벤트 팩토리 - 타입 안전한 이벤트 생성
+ */
+import type { AgentId, TaskId, AgendaId } from "../types";
+import type { PhaseChangedEvent, ContextUpdatedEvent, StateAgentRegisteredEvent, StateAgentUpdatedEvent, StateTaskCreatedEvent, StateTaskAssignedEvent, StateTaskCompletedEvent, StateTaskFailedEvent, AgentRegisteredEvent, AgentStatusChangedEvent, AgentUpdatedEvent, AgentRemovedEvent, TaskCreatedEvent, TaskAssignedEvent, TaskStartedEvent, TaskStatusChangedEvent, TaskCompletedEvent, TaskFailedEvent, TaskCancelledEvent, DecisionsAgendaCreatedEvent, DecisionsAgendaStartedEvent, DecisionsOpinionSubmittedEvent, DecisionsVotingStartedEvent, DecisionsVoteSubmittedEvent, DecisionsVotingEndedEvent, DecisionsConsensusReachedEvent, DecisionsAgendaResolvedEvent, AgendaSubmittedEvent, AgendaStatusChangedEvent, OpinionSubmittedEvent, VoteRequestedEvent, ConsensusReachedEvent, VotingCompletedEvent, FactAddedEvent, FactUpdatedEvent, FactRemovedEvent, InferenceAddedEvent, KnowledgePatternLearnedEvent, PatternAddedEvent, SystemSnapshotCreatedEvent, SystemSnapshotRestoredEvent, SystemErrorEvent, VersionConflictEvent, StateInitializedEvent, SnapshotCreatedEvent, SnapshotRestoredEvent, BoardPhase, AgentStatus, TaskStatus, AgendaStatus, Task, Agenda, Opinion, Resolution, Fact, Inference, Pattern, TaskError } from "./types";
+/**
+ * 이벤트 생성 옵션
+ */
+export interface CreateEventOptions {
+    /** 상관 ID */
+    correlationId?: string;
+    /** 소스 (기본: 'system') */
+    source?: AgentId | "system";
+}
+/**
+ * 이벤트 팩토리
+ * @description 타입 안전한 이벤트 생성
+ */
+export declare class EventFactory {
+    private idGenerator;
+    constructor(idGenerator?: () => string);
+    createPhaseChanged(previousPhase: BoardPhase, newPhase: BoardPhase, optionsOrSource?: CreateEventOptions | AgentId | "system"): PhaseChangedEvent;
+    createContextUpdated(key: string, previousValue: unknown, newValue: unknown, options?: CreateEventOptions): ContextUpdatedEvent;
+    createStateAgentRegistered(agent: AgentStatus, options?: CreateEventOptions): StateAgentRegisteredEvent;
+    createStateAgentUpdated(agentId: AgentId, previousStatus: AgentStatus, newStatus: AgentStatus, options?: CreateEventOptions): StateAgentUpdatedEvent;
+    createStateTaskCreated(task: Task, options?: CreateEventOptions): StateTaskCreatedEvent;
+    createStateTaskAssigned(taskId: TaskId, assignedTo: AgentId, options?: CreateEventOptions): StateTaskAssignedEvent;
+    createStateTaskCompleted(taskId: TaskId, result: unknown, duration: number, options?: CreateEventOptions): StateTaskCompletedEvent;
+    createStateTaskFailed(taskId: TaskId, error: TaskError, retryable: boolean, options?: CreateEventOptions): StateTaskFailedEvent;
+    createAgentRegistered(agent: AgentStatus, options?: CreateEventOptions): AgentRegisteredEvent;
+    createAgentStatusChanged(agentId: AgentId, previousStatus: AgentStatus, newStatus: AgentStatus, options?: CreateEventOptions): AgentStatusChangedEvent;
+    createAgentRemoved(agentId: AgentId, reason: string, options?: CreateEventOptions): AgentRemovedEvent;
+    createAgentUpdated(agentId: AgentId, changes: Partial<AgentStatus>, previousValues: Partial<AgentStatus>, options?: CreateEventOptions): AgentUpdatedEvent;
+    createTaskCreated(task: Task, options?: CreateEventOptions): TaskCreatedEvent;
+    createTaskAssigned(taskId: TaskId, agentId: AgentId, options?: CreateEventOptions): TaskAssignedEvent;
+    createTaskStatusChanged(taskId: TaskId, previousStatus: TaskStatus, newStatus: TaskStatus, options?: CreateEventOptions): TaskStatusChangedEvent;
+    createTaskCompleted(taskId: TaskId, outputs: unknown, duration: number, options?: CreateEventOptions): TaskCompletedEvent;
+    createTaskFailed(taskId: TaskId, error: TaskError, duration: number, options?: CreateEventOptions): TaskFailedEvent;
+    createTaskStarted(taskId: TaskId, agentId: AgentId, options?: CreateEventOptions): TaskStartedEvent;
+    createTaskCancelled(taskId: TaskId, reason: string, options?: CreateEventOptions): TaskCancelledEvent;
+    createDecisionsAgendaCreated(agenda: Agenda, options?: CreateEventOptions): DecisionsAgendaCreatedEvent;
+    createDecisionsAgendaStarted(agendaId: AgendaId, options?: CreateEventOptions): DecisionsAgendaStartedEvent;
+    createDecisionsOpinionSubmitted(opinion: Opinion, options?: CreateEventOptions): DecisionsOpinionSubmittedEvent;
+    createDecisionsVotingStarted(agendaId: AgendaId, deadline: Date, options?: CreateEventOptions): DecisionsVotingStartedEvent;
+    createDecisionsVoteSubmitted(agendaId: AgendaId, agentId: AgentId, vote: "approve" | "reject" | "abstain", options?: CreateEventOptions): DecisionsVoteSubmittedEvent;
+    createDecisionsVotingEnded(agendaId: AgendaId, result: Resolution, options?: CreateEventOptions): DecisionsVotingEndedEvent;
+    createDecisionsConsensusReached(resolution: Resolution, options?: CreateEventOptions): DecisionsConsensusReachedEvent;
+    createDecisionsAgendaResolved(agendaId: AgendaId, resolution: Resolution, options?: CreateEventOptions): DecisionsAgendaResolvedEvent;
+    createAgendaSubmitted(agenda: Agenda, options?: CreateEventOptions): AgendaSubmittedEvent;
+    createAgendaStatusChanged(agendaId: AgendaId, previousStatus: AgendaStatus, newStatus: AgendaStatus, options?: CreateEventOptions): AgendaStatusChangedEvent;
+    createOpinionSubmitted(opinion: Opinion, options?: CreateEventOptions): OpinionSubmittedEvent;
+    createVoteRequested(agendaId: AgendaId, deadline: Date, requiredVoters: AgentId[], options?: CreateEventOptions): VoteRequestedEvent;
+    createConsensusReached(resolution: Resolution, options?: CreateEventOptions): ConsensusReachedEvent;
+    createVotingCompleted(agendaId: AgendaId, result: {
+        passed: boolean;
+        method: string;
+        summary: {
+            total: number;
+            approve: number;
+            reject: number;
+            abstain: number;
+            approvalRate: number;
+            quorumReached: boolean;
+        };
+    }, options?: CreateEventOptions): VotingCompletedEvent;
+    createFactAdded(fact: Fact, options?: CreateEventOptions): FactAddedEvent;
+    createInferenceAdded(inference: Inference, options?: CreateEventOptions): InferenceAddedEvent;
+    createKnowledgePatternLearned(pattern: Pattern, options?: CreateEventOptions): KnowledgePatternLearnedEvent;
+    createFactUpdated(factId: string, changes: Partial<Fact>, previousValues?: Partial<Fact>, options?: CreateEventOptions): FactUpdatedEvent;
+    createFactRemoved(factId: string, reason: string, options?: CreateEventOptions): FactRemovedEvent;
+    createPatternAdded(pattern: Pattern, options?: CreateEventOptions): PatternAddedEvent;
+    createSystemSnapshotCreated(snapshotId: string, timestamp: Date, options?: CreateEventOptions): SystemSnapshotCreatedEvent;
+    createSystemSnapshotRestored(snapshotId: string, timestamp: Date, options?: CreateEventOptions): SystemSnapshotRestoredEvent;
+    createSystemError(code: string, message: string, details?: unknown, options?: CreateEventOptions): SystemErrorEvent;
+    createVersionConflict(path: string, expectedVersion: number, actualVersion: number, options?: CreateEventOptions): VersionConflictEvent;
+    createStateInitialized(sessionId: string, options?: CreateEventOptions): StateInitializedEvent;
+    createSnapshotCreated(snapshotId: string, version: number, options?: CreateEventOptions): SnapshotCreatedEvent;
+    createSnapshotRestored(snapshotId: string, previousVersion: number, restoredVersion: number, options?: CreateEventOptions): SnapshotRestoredEvent;
+}

package/dist/blackboard/events/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @module events/index
+ * @description 이벤트 모듈 exports
+ */
+export type { EventCategory, BaseEvent, EventType, EventByType, Event, } from './types';
+export type { Event as BusEvent } from './types';
+export type { PhaseChangedEvent, ContextUpdatedEvent, StateAgentRegisteredEvent, StateAgentUpdatedEvent, StateTaskCreatedEvent, StateTaskAssignedEvent, StateTaskCompletedEvent, StateTaskFailedEvent, } from './types';
+export type { AgentRegisteredEvent, AgentStatusChangedEvent, AgentRemovedEvent, } from './types';
+export type { TaskCreatedEvent, TaskAssignedEvent, TaskStatusChangedEvent, TaskCompletedEvent, TaskFailedEvent, } from './types';
+export type { DecisionsAgendaCreatedEvent, DecisionsAgendaStartedEvent, DecisionsOpinionSubmittedEvent, DecisionsVotingStartedEvent, DecisionsVoteSubmittedEvent, DecisionsVotingEndedEvent, DecisionsConsensusReachedEvent, DecisionsAgendaResolvedEvent, AgendaSubmittedEvent, AgendaStatusChangedEvent, OpinionSubmittedEvent, VoteRequestedEvent, ConsensusReachedEvent, } from './types';
+export type { AgendaCreatedDomainEvent, AgendaUpdatedDomainEvent, AgendaStatusChangedDomainEvent, AgendaDeletedDomainEvent, } from './types';
+export type { FactAddedEvent, InferenceAddedEvent, KnowledgePatternLearnedEvent, } from './types';
+export type { SystemSnapshotCreatedEvent, SystemSnapshotRestoredEvent, SystemErrorEvent, VersionConflictEvent, } from './types';
+export { EventBus, EventTimeoutError } from './event-bus';
+export type { EventHandler, Unsubscribe, EventFilter, EventBusOptions, EventBusStats, } from './event-bus';
+export { EventFactory } from './event-factory';
+export type { CreateEventOptions } from './event-factory';