@obora/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obora Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# @obora/runtime
+
+Core execution engine for Obora AI Control Runtime.
+
+## Installation
+
+```bash
+npm install @obora/runtime
+```
+
+## Overview
+
+The runtime package provides:
+
+- **Execution Cells** — Isolated AI execution boundaries
+- **Policy Engine** — Rule-based control for tools and actions
+- **Audit Trail** — Full event trace for compliance
+- **Recovery Engine** — Failure handling strategies
+- **Consensus System** — Multi-agent agreement gates
+- **Plugin System** — Extensible architecture
+
+## Architecture
+
+```
+@obora/runtime
+├── cell/              # Execution cells (actor-based)
+│   ├── ExecutionCell
+│   ├── CellManager
+│   └── AgentPool
+├── policy/            # Policy engine
+│   ├── PolicyEngine
+│   ├── PolicyEvaluator
+│   └── expressions/
+├── audit/             # Audit trail
+│   ├── InMemoryAuditStore
+│   ├── AuditTrail
+│   └── events/
+├── recovery/          # Recovery engine
+│   ├── RecoveryEngine
+│   ├── RetryStrategy
+│   └── SupervisionTree
+├── consensus/         # Consensus system
+│   ├── ConsensusRuleEngine
+│   ├── VotingSessionStore
+│   └── AgendaStore
+├── patterns/          # Built-in patterns
+│   ├── PipelinePattern
+│   ├── ConsensusPattern
+│   ├── PeerReviewPattern
+│   ├── SupervisorPattern
+│   └── ...
+├── state/             # State management
+│   ├── snapshot/
+│   └── types/
+└── plugins/           # Plugin system
+    ├── PluginRegistry
+    ├── PluginLoader
+    └── builtins
+```
+
+## Key Exports
+
+### Policy Engine
+
+```typescript
+import { PolicyEngine, PolicyEvaluator } from "@obora/runtime";
+
+const engine = new PolicyEngine();
+engine.register({
+  name: "no-destructive-ops",
+  condition: "tool.name matches 'delete*'",
+  effect: "deny",
+  message: "Destructive operations not allowed"
+});
+
+const result = engine.evaluate({ tool: { name: "delete_file" } });
+// { allowed: false, reason: "Destructive operations not allowed" }
+```
+
+### Audit Trail
+
+```typescript
+import { InMemoryAuditStore } from "@obora/runtime";
+
+const store = new InMemoryAuditStore();
+await store.record({
+  type: "step_start",
+  executionId: "exec-1",
+  stepName: "plan",
+  timestamp: new Date()
+});
+
+const events = await store.query({ executionId: "exec-1" });
+```
+
+### Recovery Engine
+
+```typescript
+import { RecoveryEngine, RetryStrategy } from "@obora/runtime";
+
+const engine = new RecoveryEngine({
+  strategies: [
+    new RetryStrategy({ maxRetries: 3, backoff: "exponential" })
+  ]
+});
+
+const result = await engine.executeWithRecovery(async () => {
+  // risky operation
+});
+```
+
+### Consensus
+
+```typescript
+import { ConsensusRuleEngine, VotingSessionStore } from "@obora/runtime";
+
+const engine = new ConsensusRuleEngine();
+const result = await engine.evaluate({
+  votes: [
+    { participant: "r1", vote: "APPROVE" },
+    { participant: "r2", vote: "APPROVE" },
+    { participant: "r3", vote: "REJECT" }
+  ],
+  rule: "majority"
+});
+// { approved: true, ratio: 0.67 }
+```
+
+### Patterns
+
+```typescript
+import {
+  PipelinePattern,
+  ConsensusPattern,
+  PeerReviewPattern,
+  SupervisorPattern,
+  FanOutFanInPattern
+} from "@obora/runtime";
+```
+
+### Plugin System
+
+```typescript
+import { PluginRegistry, registerBuiltinPlugins } from "@obora/runtime";
+
+const registry = new PluginRegistry();
+await registerBuiltinPlugins(registry);
+
+// Register custom plugin
+registry.register({
+  name: "my-tool",
+  version: "1.0.0",
+  type: "tool",
+  schema: { ... },
+  execute: async (params) => { ... }
+});
+```
+
+## Plugin Types
+
+| Type | Interface | Description |
+|------|-----------|-------------|
+| `agent` | `AgentPlugin` | Custom agent implementations |
+| `tool` | `ToolPlugin` | External tool integrations |
+| `pattern` | `PatternPlugin` | Workflow patterns |
+| `policy-rule` | `PolicyRulePlugin` | Custom policy rules |
+| `recovery-strategy` | `RecoveryStrategyPlugin` | Failure recovery |
+| `consensus-rule` | `ConsensusRulePlugin` | Consensus rules |
+| `audit-store` | `AuditStorePlugin` | Audit persistence |
+| `state-transform` | `StateTransformPlugin` | State transformations |
+
+## Storage
+
+```typescript
+import { SQLiteStorageAdapter } from "@obora/runtime/storage";
+
+const storage = new SQLiteStorageAdapter({ path: "./data.db" });
+await storage.initialize();
+```
+
+## License
+
+MIT

package/dist/_legacy/actor/base/BaseActor.d.ts

@@ -0,0 +1,87 @@
+import type { Action } from "../types/action";
+import { Actor, ActorId, ActorRole, ActorStatus, ActorLifecycleStatus } from "../types/actor";
+import type { IBlackboard } from "../types/blackboard";
+import type { IMessageBus, Message } from "../types/message";
+import { ActorMetrics } from "../types/metrics";
+import type { Observation } from "../types/observation";
+import type { Result } from "../types/result";
+/**
+ * Actor 구현을 위한 추상 기본 클래스 (스펙 기준)
+ *
+ * 구체적인 Actor 구현 시 이 클래스를 상속받아 필요한 메서드를 구현합니다.
+ *
+ * 참고: [[spec/13-actor.md|13-actor.md]]
+ */
+export declare abstract class BaseActor implements Actor {
+    readonly id: ActorId;
+    readonly name: string;
+    readonly role: ActorRole;
+    board: IBlackboard;
+    messageBus: IMessageBus;
+    private _status;
+    lastActivity: Date;
+    createdAt: Date;
+    metrics: ActorMetrics;
+    private subscriptions;
+    constructor(id: ActorId, name: string, role: ActorRole, board: IBlackboard, messageBus: IMessageBus);
+    get status(): ActorStatus;
+    protected setStatus(newStatus: ActorLifecycleStatus): void;
+    /**
+     * 하위 클래스에서 observe()를 구현해야 합니다.
+     * 동기 또는 비동기 구현 모두 가능합니다.
+     */
+    abstract observe(): Observation | Promise<Observation>;
+    /**
+     * 하위 클래스에서 think()를 구현해야 합니다.
+     * 동기 또는 비동기 구현 모두 가능합니다.
+     */
+    abstract think(observation: Observation): Action | Promise<Action>;
+    /**
+     * 하위 클래스에서 act()를 구현해야 합니다.
+     * 동기 또는 비동기 구현 모두 가능합니다.
+     */
+    abstract act(action: Action): Result | Promise<Result>;
+    /**
+     * receive()의 기본 구현 - 메시지 처리
+     */
+    receive(message: Message): Promise<void>;
+    /**
+     * report()의 기본 구현 - Blackboard에 결과 기록
+     * 동기 또는 비동기 구현 모두 가능합니다.
+     */
+    report(result: Result): void | Promise<void>;
+    /**
+     * start()의 기본 구현
+     */
+    start(): Promise<void>;
+    /**
+     * stop()의 기본 구현
+     */
+    stop(): Promise<void>;
+    /**
+     * restart()의 기본 구현
+     */
+    restart(): Promise<void>;
+    /**
+     * isAlive() 기본 구현
+     */
+    isAlive(): boolean;
+    /**
+     * getStatus() 기본 구현
+     */
+    getStatus(): ActorStatus;
+    /**
+     * 메트릭 업데이트
+     */
+    protected updateMetrics(result: Result): void;
+    private handleTaskAssign;
+    private handlePing;
+    private handleStatusRequest;
+    protected handleCustomMessage(_message: Message): void;
+    private teardownMessageHandlers;
+    private setupMessageHandlers;
+    private heartbeatTimer?;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private updateLastActivity;
+}

package/dist/_legacy/actor/pool/ActorPool.d.ts

@@ -0,0 +1,194 @@
+import type { ActorFactory } from "../runtime/types";
+import type { ActorId, ActorRole, ActorStatus } from "../types/actor";
+import type { IBlackboard } from "../types/actor";
+import type { IMessageBus } from "../types/message";
+/**
+ * Actor Pool 설정
+ */
+export interface PoolConfig {
+    /** 풀 이름 */
+    name: string;
+    /** Actor 역할 (풀 내 모든 Actor는 동일 역할) */
+    role: ActorRole;
+    /** Actor 유형 */
+    type: string;
+    /** 초기 Actor 수 */
+    initialSize?: number;
+    /** 최소 Actor 수 */
+    minSize?: number;
+    /** 최대 Actor 수 */
+    maxSize?: number;
+    /** Idle 타임아웃 (ms) - 지정 시간 동안 작업 없으면 Actor 종료 */
+    idleTimeout?: number;
+    /** 확장 전략 */
+    scaleStrategy?: "fixed" | "dynamic" | "adaptive";
+    /** 작업 분배 전략 */
+    dispatchStrategy?: "round-robin" | "least-busy" | "random";
+    /** 작업 큐 최대 크기 */
+    maxQueueSize?: number;
+    /** 작업 대기 타임아웃 (ms) */
+    taskTimeout?: number;
+    /** 디버그 모드 */
+    debug?: boolean;
+}
+/**
+ * 작업
+ */
+export interface Task<T = unknown> {
+    /** 작업 ID */
+    id: string;
+    /** 작업 데이터 */
+    data: T;
+    /** 생성 시간 */
+    createdAt: Date;
+    /** 우선순위 (높을수록 우선) */
+    priority: number;
+    /** 만료 시간 */
+    expiresAt?: Date;
+    /** 완료 콜백 */
+    onComplete?: (result: unknown, error?: Error) => void;
+}
+/**
+ * 작업 결과
+ */
+export interface TaskResult {
+    /** 작업 ID */
+    taskId: string;
+    /** 처리한 Actor ID */
+    actorId: ActorId;
+    /** 결과 데이터 */
+    result: unknown;
+    /** 에러 (실패 시) */
+    error?: Error;
+    /** 시작 시간 */
+    startedAt: Date;
+    /** 완료 시간 */
+    completedAt: Date;
+    /** 실행 시간 (ms) */
+    duration: number;
+}
+/**
+ * Actor Pool 메트릭
+ */
+export interface PoolMetrics {
+    /** 총 Actor 수 */
+    totalActors: number;
+    /** 활성 Actor 수 */
+    activeActors: number;
+    /** Idle 상태 Actor 수 */
+    idleActors: number;
+    /** 에러 상태 Actor 수 */
+    errorActors: number;
+    /** 대기열 크기 */
+    queueSize: number;
+    /** 평균 대기 시간 (ms) */
+    averageQueueTime: number;
+    /** 처리량 */
+    throughput: {
+        messagesPerSecond: number;
+        actionsPerSecond: number;
+    };
+    /** 이용률 (0.0 ~ 1.0) */
+    utilization: number;
+}
+/**
+ * Actor Pool
+ *
+ * 동적으로 확장/축소 가능한 Actor 풀을 관리하고,
+ * 작업을 분배하여 효율적인 리소스 사용을 제공합니다.
+ */
+export declare class ActorPool {
+    private readonly config;
+    private readonly board;
+    private readonly messageBus;
+    private readonly factory;
+    private readonly actors;
+    private readonly taskQueue;
+    private readonly inProgress;
+    private readonly completedTasks;
+    private readonly pendingResults;
+    private readonly waitingTasks;
+    private readonly actorConfigs;
+    private readonly idleTimers;
+    private readonly metrics;
+    private isRunning;
+    private roundRobinIndex;
+    private scaleTimer?;
+    private dispatchTimer?;
+    constructor(config: PoolConfig, board: IBlackboard, factory: ActorFactory, messageBus?: IMessageBus);
+    /**
+     * 풀 시작
+     */
+    start(): Promise<void>;
+    /**
+     * 풀 종료
+     */
+    stop(): Promise<void>;
+    /**
+     * 작업 제출
+     * @param data 작업 데이터
+     * @param priority 우선순위 (높을수록 우선)
+     * @param expiresIn 만료 시간 (ms, 선택)
+     * @returns 작업 ID
+     */
+    submit<T = unknown>(data: T, priority?: number, expiresIn?: number): Promise<string>;
+    /**
+     * 작업 제출 및 결과 대기
+     * @param data 작업 데이터
+     * @param priority 우선순위
+     * @returns 작업 결과
+     */
+    submitAndWait<T = unknown, R = unknown>(data: T, priority?: number): Promise<R>;
+    /**
+     * 풀 크기 조정
+     * @param size 목표 크기
+     */
+    scaleTo(size: number): Promise<void>;
+    /**
+     * 풀 크기 증가
+     * @param count 증가할 Actor 수
+     */
+    scaleUp(count?: number): Promise<void>;
+    /**
+     * 풀 크기 감소
+     * @param count 감소할 Actor 수
+     */
+    scaleDown(count?: number): Promise<void>;
+    /**
+     * 풀 메트릭 조회
+     */
+    getMetrics(): PoolMetrics;
+    /**
+     * Actor 목록 조회
+     */
+    getActors(): ActorId[];
+    /**
+     * Actor 상태 조회
+     */
+    getActorStatus(actorId: ActorId): ActorStatus;
+    /**
+     * 풀 이름
+     */
+    get name(): string;
+    private validateConfig;
+    private spawnActor;
+    private removeIdleActors;
+    private removeActor;
+    private selectActor;
+    private selectRoundRobin;
+    private selectLeastBusy;
+    private selectRandom;
+    private dispatchTaskToActor;
+    private recordTaskResult;
+    private enqueueTask;
+    private startDispatch;
+    private startAutoScale;
+    private autoScale;
+    private startIdleTimer;
+    private resetIdleTimer;
+    private isActorBusy;
+    private waitForTaskResult;
+    private clearTimers;
+    private updateMetrics;
+    private log;
+}

package/dist/_legacy/actor/pool/NoOpMessageBus.d.ts

@@ -0,0 +1,16 @@
+import type { IMessageBus, Message, MessageType, UnsubscribeFn } from "../types/message";
+import type { ActorId } from "../types/actor";
+/**
+ * No-Op MessageBus - 기본값으로 사용되는 빈 구현
+ */
+export declare class NoOpMessageBus implements IMessageBus {
+    send(message: Message): void;
+    sendTo(to: ActorId, message: Omit<Message, "to">): void;
+    broadcast(message: Omit<Message, "to">): void;
+    receive(handler: (message: Message) => void): void;
+    request<T>(message: Message, timeoutMs?: number): Promise<Message<T>>;
+    subscribe(messageType: MessageType, handler: (message: Message) => void): UnsubscribeFn;
+    getQueueSize(actorId: ActorId): number;
+    clearQueue(actorId: ActorId): void;
+    filter(predicate: (message: Message) => boolean): Message[];
+}

package/dist/_legacy/actor/pool/PoolManager.d.ts

@@ -0,0 +1,76 @@
+import type { ActorFactory } from "../runtime/types";
+import type { IBlackboard } from "../types/actor";
+import type { IMessageBus } from "../types/message";
+import { ActorPool, PoolConfig, PoolMetrics } from "./ActorPool";
+/**
+ * Pool Manager
+ *
+ * 여러 Actor Pool을 관리하는 매니저입니다.
+ */
+export declare class PoolManager {
+    private readonly board;
+    private readonly messageBus;
+    private readonly factory;
+    private readonly pools;
+    private isRunning;
+    constructor(board: IBlackboard, factory: ActorFactory, messageBus?: IMessageBus);
+    /**
+     * 매니저 시작
+     */
+    start(): Promise<void>;
+    /**
+     * 매니저 종료
+     */
+    stop(): Promise<void>;
+    /**
+     * Pool 등록
+     * @param config Pool 설정
+     * @returns 생성된 Pool
+     */
+    registerPool(config: PoolConfig): ActorPool;
+    /**
+     * Pool 등록 해제
+     * @param name Pool 이름
+     */
+    unregisterPool(name: string): Promise<void>;
+    /**
+     * Pool 조회
+     * @param name Pool 이름
+     * @returns Pool 인스턴스
+     */
+    getPool(name: string): ActorPool;
+    /**
+     * Pool 존재 여부 확인
+     * @param name Pool 이름
+     * @returns 존재 여부
+     */
+    hasPool(name: string): boolean;
+    /**
+     * 모든 Pool 이름 조회
+     * @returns Pool 이름 배열
+     */
+    listPools(): string[];
+    /**
+     * 모든 Pool의 메트릭 조회
+     * @returns Pool 이름별 메트릭 맵
+     */
+    getAllMetrics(): Map<string, PoolMetrics>;
+    /**
+     * 특정 Pool의 메트릭 조회
+     * @param name Pool 이름
+     * @returns Pool 메트릭
+     */
+    getPoolMetrics(name: string): PoolMetrics;
+    /**
+     * Pool 개수
+     */
+    size(): number;
+    /**
+     * 실행 상태
+     */
+    getStatus(): {
+        running: boolean;
+        poolCount: number;
+    };
+    private log;
+}

package/dist/_legacy/actor/pool/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./ActorPool";
+export * from "./PoolManager";
+export * from "./NoOpMessageBus";

package/dist/_legacy/actor/runtime/ActorRunner.d.ts

@@ -0,0 +1,54 @@
+import type { Actor } from "../types/actor";
+/**
+ * Actor 실행 루프 옵션
+ */
+export interface RunnerOptions {
+    /** 실행 간격 (ms) */
+    interval?: number;
+    /** 최대 연속 실행 횟수 */
+    maxIterations?: number;
+    /** 에러 발생 시 중지 여부 */
+    stopOnError?: boolean;
+    /** 종료 조건 콜백 */
+    stopCondition?: () => boolean | Promise<boolean>;
+    /** 디버그 모드 */
+    debug?: boolean;
+}
+/**
+ * Actor 실행 루프
+ *
+ * Actor의 observe-think-act-report 사이클을 반복 실행합니다.
+ */
+export declare class ActorRunner {
+    private readonly actor;
+    private readonly options;
+    private isRunning;
+    private iterationCount;
+    private abortController;
+    constructor(actor: Actor, options?: RunnerOptions);
+    /**
+     * 실행 루프 시작
+     */
+    start(): Promise<void>;
+    /**
+     * 실행 루프 중지
+     */
+    stop(): void;
+    /**
+     * 현재 실행 중인지 확인
+     */
+    running(): boolean;
+    /**
+     * 현재 반복 횟수
+     */
+    getIterationCount(): number;
+    private runCycle;
+    private shouldStop;
+    /**
+     * 내부 로그 출력.
+     *
+     * - `error`가 전달되면 `debug` 옵션과 무관하게 `console.error`로 항상 출력합니다.
+     * - 일반 로그는 `debug: true`일 때만 `console.log`로 출력합니다.
+     */
+    private log;
+}