@obora/runtime 0.1.0

package/dist/blackboard/types/knowledge.d.ts

@@ -0,0 +1,224 @@
+/**
+ * @module knowledge
+ * @description 지식 관련 타입 정의 - Fact, Inference, Pattern
+ */
+import type { Identifiable, Timestamped } from './base';
+import type { AgentId } from './base';
+/**
+ * 추론 방법
+ * @description 사실로부터 결론을 도출하는 방법
+ */
+export type InferenceMethod = 'deduction' | 'induction' | 'abduction';
+/**
+ * 사실 (Fact)
+ * @description 검증된 정보
+ *
+ * @example
+ * ```typescript
+ * const fact: Fact = {
+ *   id: 'fact-001',
+ *   content: '2025년 Q4 매출이 전년 대비 20% 증가',
+ *   source: createAgentId('analyst-agent'),
+ *   confidence: 0.95,
+ *   category: 'finance',
+ *   tags: ['revenue', 'growth'],
+ *   expiresAt: null,
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ * };
+ * ```
+ */
+export interface Fact extends Identifiable, Timestamped {
+    /** 사실 내용 */
+    content: string;
+    /** 출처 에이전트 */
+    source: AgentId;
+    /** 신뢰도 (0.0 - 1.0) */
+    confidence: number;
+    /** 카테고리 */
+    category: string;
+    /** 태그 */
+    tags: string[];
+    /** 유효 기간 (만료 시간, null이면 영구) */
+    expiresAt: Date | null;
+}
+/**
+ * 추론 (Inference)
+ * @description 사실들로부터 도출된 결론
+ *
+ * @example
+ * ```typescript
+ * const inference: Inference = {
+ *   id: 'inference-001',
+ *   conclusion: '고객 만족도가 매출 증가와 상관관계가 있음',
+ *   premises: ['fact-001', 'fact-002'],
+ *   source: createAgentId('analyst-agent'),
+ *   confidence: 0.8,
+ *   tags: ['correlation'],
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ * };
+ * ```
+ */
+export interface Inference extends Identifiable, Timestamped {
+    /** 결론 */
+    conclusion: string;
+    /** 전제 (참조하는 Fact ID들) */
+    premises: string[];
+    /** 추론한 에이전트 (deprecated: source 사용) */
+    derivedBy?: AgentId;
+    /** 출처 에이전트 */
+    source: AgentId;
+    /** 추론 방법 */
+    method?: InferenceMethod;
+    /** 신뢰도 */
+    confidence: number;
+    /** 태그 */
+    tags: string[];
+}
+/**
+ * 패턴 조건/결과 항목
+ */
+export interface PatternCondition {
+    type: string;
+    value: string;
+}
+/**
+ * 패턴 (Pattern)
+ * @description 학습된 패턴
+ *
+ * @example
+ * ```typescript
+ * const pattern: Pattern = {
+ *   id: 'pattern-001',
+ *   name: '매출 증가 패턴',
+ *   description: '고객 만족도 상승 후 2달 내 매출 증가',
+ *   conditions: [{ type: 'trigger', value: 'satisfaction_up' }],
+ *   consequences: [{ type: 'result', value: 'revenue_increase' }],
+ *   confidence: 0.85,
+ *   tags: ['finance'],
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ * };
+ * ```
+ */
+export interface Pattern extends Identifiable, Timestamped {
+    /** 패턴 이름 */
+    name: string;
+    /** 패턴 설명 */
+    description: string;
+    /** 패턴 조건 */
+    conditions: PatternCondition[];
+    /** 패턴 결과 */
+    consequences: PatternCondition[];
+    /** 신뢰도 */
+    confidence: number;
+    /** 태그 */
+    tags: string[];
+    /** 발견한 에이전트 (optional) */
+    discoveredBy?: AgentId;
+    /** 적용 횟수 */
+    usageCount?: number;
+    /** 성공률 */
+    successRate?: number;
+}
+/**
+ * 사실 생성 옵션
+ * @description 새 사실 생성 시 필요한 필드
+ */
+export interface FactCreateInput {
+    /** 사실 내용 */
+    content: string;
+    /** 출처 에이전트 */
+    source: AgentId;
+    /** 신뢰도 */
+    confidence: number;
+    /** 카테고리 */
+    category: string;
+    /** 태그 */
+    tags?: string[];
+    /** 유효 기간 (선택) */
+    expiresAt?: Date | null;
+}
+/**
+ * 추론 생성 옵션
+ * @description 새 추론 생성 시 필요한 필드
+ */
+export interface InferenceCreateInput {
+    /** 결론 */
+    conclusion: string;
+    /** 전제 (참조하는 Fact ID들) */
+    premises: string[];
+    /** 출처 에이전트 */
+    source: AgentId;
+    /** 추론 방법 (optional) */
+    method?: InferenceMethod;
+    /** 신뢰도 */
+    confidence: number;
+    /** 태그 */
+    tags?: string[];
+}
+/**
+ * 패턴 생성 옵션
+ * @description 새 패턴 생성 시 필요한 필드
+ */
+export interface PatternCreateInput {
+    /** 패턴 이름 */
+    name: string;
+    /** 패턴 설명 */
+    description: string;
+    /** 패턴 조건 */
+    conditions: PatternCondition[];
+    /** 패턴 결과 */
+    consequences: PatternCondition[];
+    /** 신뢰도 */
+    confidence: number;
+    /** 태그 */
+    tags?: string[];
+    /** 발견한 에이전트 (optional) */
+    discoveredBy?: AgentId;
+    /** 초기 적용 횟수 */
+    usageCount?: number;
+    /** 초기 성공률 */
+    successRate?: number;
+}
+/**
+ * 지식 검색 쿼리
+ * @description 지식 섹션에서 검색하기 위한 쿼리 옵션
+ */
+export interface KnowledgeQuery {
+    /** 검색할 카테고리 */
+    category?: string;
+    /** 검색할 태그 (복수) */
+    tags?: string[];
+    /** 검색할 태그 (단일) */
+    tag?: string;
+    /** 최소 신뢰도 */
+    minConfidence?: number;
+    /** 만료되지 않은 것만 검색 */
+    validOnly?: boolean;
+    /** 출처 에이전트 ID */
+    source?: AgentId;
+    /** 검색 텍스트 */
+    text?: string;
+}
+/**
+ * 추론 검색 쿼리
+ */
+export interface InferenceQuery {
+    /** 출처 에이전트 */
+    source?: AgentId;
+    /** 전제 포함 */
+    premises?: string[];
+    /** 최소 신뢰도 */
+    minConfidence?: number;
+}
+/**
+ * 패턴 검색 쿼리
+ */
+export interface PatternQuery {
+    /** 태그 */
+    tag?: string;
+    /** 최소 신뢰도 */
+    minConfidence?: number;
+}

package/dist/blackboard/types/message.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @module message
+ * @description 메시지 관련 타입 정의
+ */
+import type { Identifiable, Timestamped } from './base';
+import type { AgentId, TaskId } from './base';
+/**
+ * 메시지 타입 enum
+ * @description 시스템 내 모든 메시지 유형
+ */
+export declare enum MessageType {
+    /** 상태 읽기 요청 */
+    STATE_READ = "state.read",
+    /** 상태 쓰기 요청 */
+    STATE_WRITE = "state.write",
+    /** 상태 구독 */
+    STATE_SUBSCRIBE = "state.subscribe",
+    /** 상태 변경 알림 */
+    STATE_UPDATED = "state.updated",
+    /** 안건 제출 요청 */
+    DECISION_REQUEST = "decision.request",
+    /** 의견 제출 */
+    OPINION_SUBMIT = "opinion.submit",
+    /** 투표 제출 */
+    VOTE_SUBMIT = "vote.submit",
+    /** 합의 도달 알림 */
+    CONSENSUS_REACHED = "consensus.reached",
+    /** 작업 할당 */
+    TASK_ASSIGN = "task.assign",
+    /** 작업 완료 */
+    TASK_COMPLETE = "task.complete",
+    /** 작업 실패 */
+    TASK_FAILED = "task.failed",
+    /** 작업 진행 상황 */
+    TASK_PROGRESS = "task.progress",
+    /** 사실 추가 */
+    KNOWLEDGE_FACT_ADD = "knowledge.fact.add",
+    /** 추론 추가 */
+    KNOWLEDGE_INFERENCE_ADD = "knowledge.inference.add",
+    /** 하트비트 */
+    HEARTBEAT = "heartbeat",
+    /** 에러 */
+    ERROR = "error",
+    /** 시스템 알림 */
+    SYSTEM_NOTIFICATION = "system.notification"
+}
+/**
+ * 메시지 기본 인터페이스
+ * @description 시스템 내에서 주고받는 모든 메시지의 기본 구조
+ * @typeParam T - 페이로드 타입
+ *
+ * @example
+ * ```typescript
+ * const message: Message<string> = {
+ *   id: 'msg-001',
+ *   type: MessageType.HEARTBEAT,
+ *   from: createAgentId('agent-001'),
+ *   to: 'broadcast',
+ *   payload: 'ping',
+ *   priority: 1,
+ *   ttl: null,
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ * };
+ * ```
+ */
+export interface Message<T = unknown> extends Identifiable, Timestamped {
+    /** 메시지 타입 */
+    type: MessageType;
+    /** 발신자 ID */
+    from: AgentId;
+    /** 수신자 ID ('broadcast'면 전체) */
+    to: AgentId | 'broadcast';
+    /** 메시지 내용 */
+    payload: T;
+    /** 상관 ID (요청-응답 연결용) */
+    correlationId?: string;
+    /** 우선순위 */
+    priority: number;
+    /** TTL (밀리초, null이면 무제한) */
+    ttl: number | null;
+}
+/**
+ * 상태 읽기 요청 페이로드
+ * @description Blackboard의 특정 섹션을 읽기 위한 요청
+ */
+export interface StateReadPayload {
+    /** 읽을 섹션 */
+    section: 'state' | 'knowledge' | 'decisions';
+    /** 경로 */
+    path: string;
+    /** 쿼리 파라미터 */
+    query?: Record<string, unknown>;
+}
+/**
+ * 상태 쓰기 요청 페이로드
+ * @description Blackboard의 특정 섹션에 쓰기 위한 요청
+ */
+export interface StateWritePayload {
+    /** 쓸 섹션 */
+    section: 'state' | 'knowledge' | 'decisions';
+    /** 경로 */
+    path: string;
+    /** 데이터 */
+    data: unknown;
+    /** 기대 버전 (optimistic locking용) */
+    expectedVersion?: number;
+}
+/**
+ * 에러 페이로드
+ * @description 에러 발생 시 전달하는 정보
+ */
+export interface ErrorPayload {
+    /** 에러 코드 */
+    code: string;
+    /** 에러 메시지 */
+    message: string;
+    /** 상세 정보 */
+    details?: Record<string, unknown>;
+    /** 재시도 가능 여부 */
+    retryable: boolean;
+}
+/**
+ * 하트비트 페이로드
+ * @description 에이전트 하트비트 정보
+ */
+export interface HeartbeatPayload {
+    /** 에이전트 ID */
+    agentId: AgentId;
+    /** 현재 작업 ID (없으면 null) */
+    currentTask?: TaskId | null;
+    /** 타임스탬프 */
+    timestamp: Date;
+    /** 추가 상태 정보 */
+    status?: Record<string, unknown>;
+}
+/**
+ * 메시지 전송 옵션
+ * @description 메시지 전송 시 설정 가능한 옵션
+ */
+export interface MessageSendOptions {
+    /** 수신자 ID */
+    to: AgentId | 'broadcast';
+    /** 메시지 타입 */
+    type: MessageType;
+    /** 우선순위 (기본: 1) */
+    priority?: number;
+    /** TTL (밀리초) */
+    ttl?: number | null;
+    /** 상관 ID */
+    correlationId?: string;
+}
+/**
+ * 메시지 핸들러 타입
+ * @description 메시지를 처리하는 핸들러 함수의 타입
+ */
+export type MessageHandler<T = unknown> = (message: Message<T>) => void | Promise<void>;
+/**
+ * 메시지 필터 타입
+ * @description 메시지를 필터링하는 조건 함수의 타입
+ */
+export type MessageFilter<T = unknown> = (message: Message<T>) => boolean;

package/dist/blackboard/types/task.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @module task
+ * @description 작업(Task) 관련 타입 정의
+ */
+import type { Identifiable, Timestamped, Versioned } from './base';
+import type { AgentId, TaskId } from './base';
+/**
+ * 작업 상태 enum
+ * @description 작업의 진행 상태를 나타냄
+ */
+export declare enum TaskStatus {
+    /** 대기 중 */
+    PENDING = "pending",
+    /** 실행 중 */
+    RUNNING = "running",
+    /** 완료됨 */
+    COMPLETED = "completed",
+    /** 실패함 */
+    FAILED = "failed",
+    /** 취소됨 */
+    CANCELLED = "cancelled"
+}
+/**
+ * 작업 우선순위
+ * @description 작업의 중요도를 나타내는 순위
+ */
+export declare enum TaskPriority {
+    LOW = 0,
+    NORMAL = 1,
+    HIGH = 2,
+    CRITICAL = 3
+}
+/**
+ * 작업 정의
+ * @description 시스템에서 실행할 작업의 정의
+ *
+ * @example
+ * ```typescript
+ * const task: Task = {
+ *   id: createTaskId('task-001'),
+ *   name: '데이터 분석',
+ *   description: '사용자 행동 데이터 분석',
+ *   assignedTo: createAgentId('agent-001'),
+ *   status: TaskStatus.PENDING,
+ *   priority: TaskPriority.HIGH,
+ *   inputs: { dataset: 'users-2026-01' },
+ *   outputs: null,
+ *   dependsOn: [],
+ *   error: null,
+ *   startedAt: null,
+ *   completedAt: null,
+ *   timeout: 3600000,
+ *   version: 1,
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ * };
+ * ```
+ */
+export interface Task extends Identifiable<TaskId>, Timestamped, Versioned {
+    /** 작업 이름 */
+    name: string;
+    /** 작업 설명 */
+    description: string;
+    /** 할당된 에이전트 */
+    assignedTo: AgentId | null;
+    /** 현재 상태 */
+    status: TaskStatus;
+    /** 우선순위 */
+    priority: TaskPriority;
+    /** 입력 데이터 */
+    inputs: Record<string, unknown>;
+    /** 출력 데이터 (완료 시) */
+    outputs: Record<string, unknown> | null;
+    /** 의존하는 작업 ID 목록 */
+    dependsOn: TaskId[];
+    /** 에러 정보 (실패 시) */
+    error: TaskError | null;
+    /** 시작 시간 */
+    startedAt: Date | null;
+    /** 완료 시간 */
+    completedAt: Date | null;
+    /** 제한 시간 (밀리초) */
+    timeout: number | null;
+}
+/**
+ * 작업 에러 정보
+ * @description 작업 실행 중 발생한 에러의 상세 정보
+ */
+export interface TaskError {
+    /** 에러 코드 */
+    code: string;
+    /** 에러 메시지 */
+    message: string;
+    /** 스택 트레이스 */
+    stack?: string;
+    /** 재시도 가능 여부 */
+    retryable: boolean;
+}
+/**
+ * 작업 생성 옵션
+ * @description 새 작업 생성 시 필요한 필드
+ */
+export interface TaskCreateInput {
+    /** 작업 이름 */
+    name: string;
+    /** 작업 설명 */
+    description: string;
+    /** 할당할 에이전트 (선택) */
+    assignedTo?: AgentId | null;
+    /** 우선순위 (기본: NORMAL) */
+    priority?: TaskPriority;
+    /** 입력 데이터 */
+    inputs?: Record<string, unknown>;
+    /** 의존하는 작업 ID 목록 */
+    dependsOn?: TaskId[];
+    /** 제한 시간 (밀리초) */
+    timeout?: number | null;
+}
+/**
+ * 작업 업데이트 옵션
+ * @description 작업 상태 업데이트를 위한 선택적 필드
+ */
+export interface TaskUpdateInput {
+    /** 새로운 상태 */
+    status?: TaskStatus;
+    /** 할당된 에이전트 */
+    assignedTo?: AgentId | null;
+    /** 우선순위 */
+    priority?: TaskPriority;
+    /** 출력 데이터 */
+    outputs?: Record<string, unknown> | null;
+    /** 에러 정보 */
+    error?: TaskError | null;
+    /** 시작 시간 */
+    startedAt?: Date | null;
+    /** 완료 시간 */
+    completedAt?: Date | null;
+}
+/**
+ * 작업 진행 상황
+ * @description 작업 실행 중의 진행 상황 보고
+ */
+export interface TaskProgress {
+    /** 작업 ID */
+    taskId: TaskId;
+    /** 진행률 (0.0 - 1.0) */
+    progress: number;
+    /** 현재 단계 설명 */
+    currentStep: string;
+    /** 남은 예상 시간 (밀리초) */
+    estimatedTimeRemaining?: number;
+    /** 추가 메시지 */
+    message?: string;
+}