@obora/runtime 0.1.0

package/dist/_legacy/actor/types/result.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @module result
+ * @description Result 타입 정의 - Action 수행 결과
+ */
+import type { ActionId } from "./action";
+import type { ActorId } from "./actor";
+/**
+ * Result 고유 ID 타입
+ * @description 브랜드 타입을 사용하여 타입 안전성을 확보
+ */
+export type ResultId = string & {
+    readonly __brand: "ResultId";
+};
+/**
+ * Result 상태
+ * @description 행동 수행 결과의 상태
+ */
+export type ResultStatus = "success" | "failure" | "partial";
+/**
+ * Result 메트릭
+ * @description 행동 수행의 성능 메트릭
+ */
+export interface ResultMetrics {
+    /** 실행 시간 (밀리초) */
+    duration: number;
+    /** 메모리 사용량 (바이트) */
+    memoryUsage?: number;
+    /** 추가 메트릭 */
+    [key: string]: unknown;
+}
+/**
+ * Result 인터페이스
+ * @description Action 수행 결과
+ */
+export interface Result {
+    /** 고유 식별자 */
+    readonly id: ResultId;
+    /** 관련 Action ID */
+    actionId: ActionId;
+    /** 결과를 생성한 액터 ID */
+    actorId: ActorId;
+    /** 결과 생성 시간 */
+    timestamp: Date;
+    /** 결과 상태 */
+    status: ResultStatus;
+    /** 출력 데이터 (성공 시) */
+    output?: unknown;
+    /** 오류 정보 (실패 시) - 문자열 형태 */
+    error?: string;
+    /** 성능 메트릭 */
+    metrics?: ResultMetrics;
+    /** 보드에 기록할 데이터 */
+    toRecord?: {
+        section: "state" | "knowledge" | "decisions";
+        data: unknown;
+    };
+}
+/**
+ * Result ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 ResultId
+ * @example
+ * ```typescript
+ * const resultId = createResultId('result-001');
+ * // 타입: ResultId
+ * ```
+ */
+export declare function createResultId(id: string): ResultId;
+/**
+ * Result ID 유효성 검사
+ * @param value - 확인할 값
+ * @returns 유효한 ResultId 여부
+ */
+export declare function isValidResultId(value: unknown): value is ResultId;
+/**
+ * 성공 Result 생성 함수
+ * @param actionId - Action ID
+ * @param actorId - 액터 ID
+ * @param output - 출력 데이터
+ * @param duration - 실행 시간 (밀리초)
+ * @returns 생성된 성공 Result 객체
+ * @example
+ * ```typescript
+ * const result = createSuccessResult(
+ *   createActionId('action-001'),
+ *   createActorId('actor-001'),
+ *   { data: 'analysis result' },
+ *   100
+ * );
+ * ```
+ */
+export declare function createSuccessResult(actionId: ActionId, actorId: ActorId, output: unknown, duration: number): Result;
+/**
+ * 실패 Result 생성 함수
+ * @param actionId - Action ID
+ * @param actorId - 액터 ID
+ * @param error - 오류 메시지
+ * @param duration - 실행 시간 (밀리초)
+ * @returns 생성된 실패 Result 객체
+ * @example
+ * ```typescript
+ * const result = createFailureResult(
+ *   createActionId('action-001'),
+ *   createActorId('actor-001'),
+ *   'Analysis failed',
+ *   50
+ * );
+ * ```
+ */
+export declare function createFailureResult(actionId: ActionId, actorId: ActorId, error: string, duration: number): Result;

package/dist/_legacy/agents/roles/analyst-agent.d.ts

@@ -0,0 +1,18 @@
+import { BaseAgent, BaseAgentConfig, AgentContext, Task, AnalystOutput } from "./base-agent";
+/**
+ * Analyst 에이전트
+ * 역할: 데이터 분석, 위험 평가, 패턴 인식
+ *
+ * 입력: AnalystInput
+ * 출력: AnalystOutput
+ */
+export declare class AnalystAgent extends BaseAgent {
+    constructor(config: Omit<BaseAgentConfig, "role">);
+    protected getDefaultSystemPrompt(): string;
+    protected act(action: unknown, context: AgentContext): Promise<unknown>;
+    protected parseResponse(content: string, task: Task): AnalystOutput;
+}
+/**
+ * 분석 에이전트 생성
+ */
+export declare function createAnalystAgent(id: string, llm: BaseAgentConfig["llm"]): AnalystAgent;

package/dist/_legacy/agents/roles/base-agent.d.ts

@@ -0,0 +1,320 @@
+import { type AgentEvent, type AgentTool } from "@mariozechner/pi-agent-core";
+import { LLMAdapter, ChatMessage } from "../llm/adapter";
+import type { Blackboard } from "../../blackboard/core/blackboard.js";
+import type { AgentId } from "../types";
+export type { AgentId };
+export declare enum AgentRole {
+    ANALYST = "analyst",
+    EXECUTOR = "executor",
+    VERIFIER = "verifier",
+    DIRECTOR = "director"
+}
+export declare enum AgentState {
+    IDLE = "idle",
+    THINKING = "thinking",
+    ACTING = "acting",
+    WAITING = "waiting",
+    ERROR = "error"
+}
+export declare enum MeetingPhase {
+    OPENING = "opening",
+    DISCUSSION = "discussion",
+    VOTING = "voting",
+    CONSENSUS = "consensus",
+    CLOSING = "closing",
+    ESCALATION = "escalation"
+}
+export interface AgentStatus {
+    id: AgentId;
+    role: AgentRole;
+    state: AgentState;
+    lastActivity: Date;
+    currentTask?: string;
+    errorCount: number;
+}
+export interface AgentContext {
+    sessionId: string;
+    board: Blackboard;
+    currentTask?: Task;
+    history: ChatMessage[];
+    signal?: AbortSignal;
+}
+export interface Task {
+    id: string;
+    type: string;
+    description: string;
+    input: Record<string, unknown>;
+    priority: number;
+    deadline?: Date;
+    metadata?: Record<string, unknown>;
+}
+export interface TaskResult {
+    taskId: string;
+    success: boolean;
+    output: unknown;
+    error?: Error;
+    duration: number;
+    tokensUsed: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+}
+export interface RuntimeExtensions {
+    tools?: AgentTool[];
+    systemPromptAppend?: string;
+}
+export declare abstract class BaseAgent {
+    readonly id: AgentId;
+    readonly role: AgentRole;
+    protected state: AgentState;
+    protected llm: LLMAdapter;
+    protected systemPrompt: string;
+    protected runtimeTools: AgentTool[];
+    protected runtimeSystemPromptAppend: string;
+    protected errorCount: number;
+    protected maxErrors: number;
+    protected thinkMaxTokens: number;
+    protected executeMaxTokens: number;
+    private readonly BLOCKED_PATTERNS;
+    private coreAgent?;
+    private unsubscribe?;
+    private currentContext?;
+    private currentTask?;
+    private latestUsage;
+    constructor(config: BaseAgentConfig);
+    execute(task: Task, context: AgentContext): Promise<TaskResult>;
+    continue(): Promise<void>;
+    subscribe(listener: (event: AgentEvent) => void): () => void;
+    protected observe(context: AgentContext): Promise<Record<string, unknown>>;
+    protected think(task: Task, observation: Record<string, unknown>, context: AgentContext): Promise<{
+        action: unknown;
+        usage: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+    }>;
+    protected abstract act(action: unknown, context: AgentContext): Promise<unknown>;
+    protected report(task: Task, result: unknown, context: AgentContext): Promise<void>;
+    protected buildMessages(task: Task, observation: Record<string, unknown>, context: AgentContext): ChatMessage[];
+    protected formatTaskAndObservation(task: Task, observation: Record<string, unknown>): string;
+    protected abstract parseResponse(content: string, task: Task): unknown;
+    protected abstract getDefaultSystemPrompt(): string;
+    configureRuntimeExtensions(extensions: RuntimeExtensions): void;
+    clearRuntimeExtensions(): void;
+    private getEffectiveSystemPrompt;
+    getStatus(): AgentStatus;
+    resetErrorCount(): void;
+    hasExceededMaxErrors(): boolean;
+    private createPiAgent;
+    /**
+     * Defines tools available to the LLM via pi-agent-core's tool-calling mechanism.
+     * These tools are registered with the Agent at creation time and executed
+     * by pi-agent-core when the LLM issues tool calls through the API.
+     *
+     * Security:
+     * - file_write/file_read/file_list: Path validated with fs.realpathSync (symlink-safe)
+     * - shell_exec: Denylist blocks dangerous command patterns
+     */
+    private createAgentTools;
+    private createExecutorTools;
+    /**
+     * Creates a stream function bridge for pi-agent-core's Agent runtime.
+     *
+     * ARCHITECTURE NOTE - Tool-Calling Loop:
+     * The tool execution loop is fully delegated to pi-agent-core's Agent class.
+     * This streamFn is called by pi-agent-core on each LLM turn. When the LLM
+     * returns tool_calls (stopReason: "toolUse"), pi-agent-core automatically:
+     *   1. Executes the matching tool from createAgentTools()
+     *   2. Appends the tool result as a "tool" message
+     *   3. Calls this streamFn again with the updated message history
+     *   4. Repeats until the LLM returns stopReason: "stop"
+     *
+     * obora-kit does NOT implement its own tool loop — pi-agent-core handles it.
+     */
+    private createStreamFn;
+    /**
+     * Delegates task execution to pi-agent-core's Agent runtime.
+     * The Agent.prompt() call triggers the full tool-calling loop internally.
+     * See createStreamFn() for the tool loop architecture.
+     */
+    private executeWithPiAgent;
+    private parseBoardReadParams;
+    private parseRoleActionParams;
+    private parseBoardWriteParams;
+    private parseFileWriteParams;
+    private parseFileReadParams;
+    private parseFileListParams;
+    private parseShellExecParams;
+    private isRecord;
+    private resolveAndValidatePath;
+    private isBlockedShellCommand;
+}
+export interface BaseAgentConfig {
+    id?: AgentId;
+    role: AgentRole;
+    llm: LLMAdapter;
+    systemPrompt?: string;
+    maxErrors?: number;
+    provider?: string;
+    model?: string;
+    sessionId?: string;
+    thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    enablePiRuntime?: boolean;
+    thinkMaxTokens?: number;
+    executeMaxTokens?: number;
+}
+/**
+ * Analyst 입력 타입
+ */
+export interface AnalystInput {
+    type: "analysis";
+    content: string;
+    goal?: string;
+    constraints?: string[];
+    resources?: string[];
+    previousPlans?: Plan[];
+    context?: Record<string, unknown>;
+}
+/**
+ * Analyst 출력 타입
+ */
+export interface AnalystOutput {
+    type: "analysis";
+    content: string;
+    summary: string;
+    keyFindings: string[];
+    recommendations: string[];
+    confidence: number;
+    reasoning: string;
+    sources?: string[];
+}
+/**
+ * Executor 입력 타입
+ */
+export interface ExecutorInput {
+    type: "execution";
+    content: string;
+    taskDescription: string;
+    inputs?: Record<string, unknown>;
+    expectedOutput?: string;
+    tools?: string[];
+    context?: Record<string, unknown>;
+}
+/**
+ * Executor 출력 타입
+ */
+export interface ExecutorOutput {
+    type: "execution";
+    content: string;
+    action: string;
+    tool?: string;
+    parameters: Record<string, unknown>;
+    steps: string[];
+    expectedOutcome: string;
+}
+/**
+ * Verifier 입력 타입
+ */
+export interface VerifierInput {
+    type: "verification";
+    content: string;
+    artifact: Artifact;
+    criteria?: string[];
+    requirements?: string[];
+    context?: Record<string, unknown>;
+}
+/**
+ * Verifier 출력 타입
+ */
+export interface VerifierOutput {
+    type: "verification";
+    content: string;
+    passed: boolean;
+    score: number;
+    checks: VerificationCheck[];
+    findings: Finding[];
+    suggestions: string[];
+}
+/**
+ * Director 입력 타입
+ */
+export interface DirectorInput {
+    type: "coordination";
+    content: string;
+    agenda: string;
+    participants: string[];
+    currentOpinions?: string[];
+    conflict?: Conflict;
+    context?: Record<string, unknown>;
+}
+/**
+ * Director 출력 타입 (스펙 14-ai-agents.md와 일치)
+ */
+export interface DirectorOutput {
+    type: "coordination";
+    content: string;
+    agenda: string;
+    participants: string[];
+    steps: CoordinationStep[];
+    timeline: string[];
+    expectedOutcome: string;
+}
+/**
+ * 검증 체크 항목
+ */
+export interface VerificationCheck {
+    name: string;
+    description: string;
+    status: "passed" | "failed" | "skipped";
+    evidence: string;
+}
+/**
+ * 발견된 이슈
+ */
+export interface Finding {
+    id: string;
+    type: "error" | "warning" | "info";
+    description: string;
+    location?: string;
+    severity: "low" | "medium" | "high" | "critical";
+}
+/**
+ * 조율 단계
+ */
+export interface CoordinationStep {
+    step: number;
+    description: string;
+    assignee?: string;
+    dependencies: string[];
+    estimatedDuration?: string;
+}
+/**
+ * 갈등 정보
+ */
+export interface Conflict {
+    id: string;
+    topic: string;
+    parties: string[];
+    positions: Record<string, string>;
+    severity: "minor" | "moderate" | "major";
+}
+/**
+ * 아티팩트
+ */
+export interface Artifact {
+    id: string;
+    type: "code" | "document" | "data" | "plan" | "review";
+    name: string;
+    content: string | Record<string, unknown>;
+}
+/**
+ * Plan 타입 (AnalystInput에서 참조)
+ */
+export interface Plan {
+    id: string;
+    description: string;
+    steps: string[];
+    status: "draft" | "approved" | "completed";
+}

package/dist/_legacy/agents/roles/director-agent.d.ts

@@ -0,0 +1,26 @@
+import { BaseAgent, BaseAgentConfig, AgentContext, Task, DirectorOutput } from "./base-agent";
+/**
+ * Director 에이전트
+ * 역할: 조율, 진행 관리, 합의 도출
+ *
+ * 입력: DirectorInput
+ * 출력: DirectorOutput
+ */
+export declare class DirectorAgent extends BaseAgent {
+    constructor(config: Omit<BaseAgentConfig, "role">);
+    protected getDefaultSystemPrompt(): string;
+    protected act(action: unknown, context: AgentContext): Promise<unknown>;
+    protected parseResponse(content: string, task: Task): DirectorOutput;
+    /**
+     * 투표 세션 시작
+     */
+    startVotingSession(agendaId: string, participants: string[], context: AgentContext): Promise<void>;
+    /**
+     * 투표 집계
+     */
+    tallyVotes(agendaId: string, context: AgentContext): Promise<Record<string, number>>;
+}
+/**
+ * 디렉터 에이전트 생성
+ */
+export declare function createDirectorAgent(id: string, llm: BaseAgentConfig["llm"]): DirectorAgent;

package/dist/_legacy/agents/roles/executor-agent.d.ts

@@ -0,0 +1,26 @@
+import { BaseAgent, BaseAgentConfig, AgentContext, Task, ExecutorOutput } from "./base-agent";
+import { ToolRegistry } from "../tools";
+/**
+ * Executor 에이전트
+ * 역할: 작업 실행, API 호출, 파일 처리
+ *
+ * 입력: ExecutorInput
+ * 출력: ExecutorOutput
+ */
+export declare class ExecutorAgent extends BaseAgent {
+    private toolRegistry?;
+    constructor(config: Omit<BaseAgentConfig, "role"> & {
+        toolRegistry?: ToolRegistry;
+    });
+    protected getDefaultSystemPrompt(): string;
+    protected act(action: unknown, context: AgentContext): Promise<unknown>;
+    protected parseResponse(content: string, task: Task): ExecutorOutput;
+    /**
+     * 도구 레지스트리 설정
+     */
+    setToolRegistry(registry: ToolRegistry): void;
+}
+/**
+ * 실행 에이전트 생성
+ */
+export declare function createExecutorAgent(id: string, llm: BaseAgentConfig["llm"], toolRegistry?: ToolRegistry): ExecutorAgent;

package/dist/_legacy/agents/roles/factory.d.ts

@@ -0,0 +1,30 @@
+import { BaseAgent } from "./base-agent";
+import type { LLMAdapter } from "../llm/adapter";
+import type { ToolRegistry } from "../tools";
+/**
+ * 에이전트 생성 설정
+ */
+export interface CreateAgentConfig {
+    id: string;
+    role: "analyst" | "executor" | "verifier" | "director";
+    llm: LLMAdapter;
+    toolRegistry?: ToolRegistry;
+    systemPrompt?: string;
+    provider?: string;
+    model?: string;
+    sessionId?: string;
+    enablePiRuntime?: boolean;
+}
+/**
+ * 에이전트 생성
+ */
+export declare function createAgent(config: CreateAgentConfig): BaseAgent;
+/**
+ * 에이전트 팀 생성
+ */
+export declare function createAgentTeam(config: Omit<CreateAgentConfig, "id" | "role"> & {
+    analysts?: number;
+    executors?: number;
+    verifiers?: number;
+    directors?: number;
+}): BaseAgent[];

package/dist/_legacy/agents/roles/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./base-agent";
+export * from "./analyst-agent";
+export * from "./executor-agent";
+export * from "./verifier-agent";
+export * from "./director-agent";
+export * from "./factory";

package/dist/_legacy/agents/roles/verifier-agent.d.ts

@@ -0,0 +1,18 @@
+import { BaseAgent, BaseAgentConfig, AgentContext, Task, VerifierOutput } from "./base-agent";
+/**
+ * Verifier 에이전트
+ * 역할: 결과 검증, 품질 체크, 정확성 확인
+ *
+ * 입력: VerifierInput
+ * 출력: VerifierOutput
+ */
+export declare class VerifierAgent extends BaseAgent {
+    constructor(config: Omit<BaseAgentConfig, "role">);
+    protected getDefaultSystemPrompt(): string;
+    protected act(action: unknown, context: AgentContext): Promise<unknown>;
+    protected parseResponse(content: string, task: Task): VerifierOutput;
+}
+/**
+ * 검증 에이전트 생성
+ */
+export declare function createVerifierAgent(id: string, llm: BaseAgentConfig["llm"]): VerifierAgent;