@obora/runtime 0.1.0

package/dist/_legacy/cli-runtime/runtime/context-builder.d.ts

@@ -0,0 +1,88 @@
+/**
+ * ContextBuilder — assembles AgentContext with a shared Blackboard
+ * for workflow execution.
+ *
+ * Responsibilities:
+ * - Create one Blackboard per workflow run (single session scope)
+ * - Build AgentContext for each step with board, task, history
+ * - Record step results/errors on the board for inter-step state sharing
+ * - Maintain single-writer: only this module writes step results to board
+ *
+ * @module @obora/cli/runtime/context-builder
+ */
+import type { ChatMessage } from "@obora/adapters";
+import type { AgentContext } from "../../agents/roles/index.js";
+import { Blackboard } from "./blackboard.js";
+import type { Step, Workflow } from "../../../_legacy/workflow/index.js";
+import type { StepResult } from "./step-executor.js";
+import type { StepErrorMetadata } from "./types.js";
+/** Metadata stored in blackboard state.context.workflow for replay/trace */
+export interface WorkflowMeta {
+    workflowName: string;
+    workflowVersion: string;
+    featureName: string;
+    startedAt: string;
+    sessionId: string;
+}
+/** Result record stored on blackboard for each step */
+export interface StepResultRecord {
+    success: boolean;
+    output: string | null;
+    error: string | null;
+    errorMeta?: StepErrorMetadata | null;
+    diagnosisCode: string | null;
+    completedAt: string | null;
+    failedAt: string | null;
+}
+/** Returns an ISO-8601 timestamp string. Injectable for deterministic tests. */
+export type Clock = () => string;
+/** Override the clock used by record* functions. Pass `null` to reset. */
+export declare function setClock(clock: Clock | null): void;
+/**
+ * Create a Blackboard instance scoped to a single workflow run.
+ *
+ * Initialises `state.context.workflow` with replay-friendly metadata and
+ * `state.steps` as an empty container for per-step results.
+ */
+export declare function createWorkflowBlackboard(sessionId: string, workflow: Workflow, featureName: string): Blackboard;
+/**
+ * Build an AgentContext for a single step execution.
+ *
+ * @param sessionId - Workflow run session ID
+ * @param board     - Shared Blackboard instance (workflow-scoped)
+ * @param step      - Current workflow step
+ * @param history   - Accumulated LLM chat history from prior steps
+ */
+export declare function buildAgentContext(sessionId: string, board: Blackboard | AgentContext["board"], step: Step, history?: ChatMessage[]): AgentContext;
+/**
+ * Record a successful step result on the blackboard.
+ * Path: `state.context.steps.<stepName>`
+ */
+export declare function recordStepResult(board: Blackboard | AgentContext["board"], stepName: string, result: StepResult): void;
+/**
+ * Record a failed step result on the blackboard.
+ * Path: `state.context.steps.<stepName>`
+ */
+export declare function recordStepError(board: Blackboard | AgentContext["board"], stepName: string, result: StepResult): void;
+/**
+ * Read a previous step's result from the blackboard.
+ * Returns null if the step has not been recorded yet.
+ *
+ * Uses a single `board.read({ strict: false })` call for atomicity
+ * and efficiency (one traversal instead of exists + read).
+ */
+export declare function readStepResult(board: Blackboard | AgentContext["board"], stepName: string): StepResultRecord | null;
+/**
+ * Maximum number of chat messages retained in the rolling history window.
+ * Prevents unbounded memory growth in long workflows while keeping enough
+ * context for downstream steps.
+ */
+export declare const MAX_HISTORY_LENGTH = 200;
+/**
+ * Append a message to the chat history, trimming the oldest entries when
+ * the history exceeds `MAX_HISTORY_LENGTH`.
+ *
+ * **Note:** Mutates the input array in-place for performance. Callers
+ * sharing the array reference should be aware of this contract.
+ */
+export declare function appendHistory(history: ChatMessage[], message: ChatMessage): void;

package/dist/_legacy/cli-runtime/runtime/retry-policy.d.ts

@@ -0,0 +1,8 @@
+export interface RetryPolicy {
+    baseDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier?: number;
+    jitterRatio?: number;
+}
+export declare function calculateDelay(attempt: number, policy: RetryPolicy): number;
+export declare function waitWithAbort(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/_legacy/cli-runtime/runtime/step-executor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * StepExecutor — bridges workflow Step to BaseAgent.execute()
+ */
+import type { Step } from "../../../_legacy/workflow/index.js";
+import { type AgentConfig } from "@obora/adapters";
+import { type ErrorCode } from "../../../_legacy/workflow/index.js";
+import type { BaseAgent, Task, AgentContext } from "../../agents/roles/index.js";
+import type { StepErrorMetadata } from "./types.js";
+export interface StepResult {
+    success: boolean;
+    output?: string;
+    error?: string;
+    diagnosisCode?: ErrorCode;
+    errorMeta?: StepErrorMetadata;
+}
+export interface AgentResolver {
+    resolve(agentName: string): BaseAgent | Promise<BaseAgent>;
+    resolve(query: {
+        agent?: string;
+        type?: string;
+        config?: AgentConfig;
+    }): BaseAgent | Promise<BaseAgent>;
+}
+export { parseDuration } from "./utils.js";
+export declare function stepToTask(step: Step): Task;
+export interface ExecuteStepOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    retryAttempts?: number;
+    resolvedAgentConfig?: AgentConfig;
+    onEvent?: (event: unknown) => void;
+}
+export declare function executeStep(step: Step, resolver: AgentResolver, context: AgentContext, options?: ExecuteStepOptions): Promise<StepResult>;

package/dist/_legacy/cli-runtime/runtime/types.d.ts

@@ -0,0 +1,12 @@
+import type { ErrorCode } from "../../../_legacy/workflow/index.js";
+export type UserFacingErrorCode = "E4001" | "E4002" | "E4003" | "E4005" | "E4006" | "E4007" | "E4010" | "E4012" | "E4013" | "E4014";
+export type InternalDiagCode = "E4011";
+export interface StepErrorMetadata {
+    code: UserFacingErrorCode;
+    message: string;
+    provider?: string;
+    statusCode?: number;
+    attempts?: number;
+    lastError?: ErrorCode;
+    failedAt?: string;
+}

package/dist/_legacy/cli-runtime/runtime/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function parseDuration(duration: string): number;
+export declare function deepFreeze<T>(value: T): Readonly<T>;

package/dist/_legacy/database/src/duckdb-client.d.ts

@@ -0,0 +1,178 @@
+/**
+ * DuckDB client for data persistence
+ * @module @obora/database/duckdb-client
+ */
+/**
+ * Project record
+ */
+export interface Project {
+    id?: number;
+    name: string;
+    path: string;
+    created_at?: string;
+    updated_at?: string;
+}
+/**
+ * Workflow run record
+ */
+export interface WorkflowRun {
+    id?: number;
+    project_id: number;
+    feature: string;
+    workflow: string;
+    mode: "auto" | "supervised" | "gated";
+    status: "pending" | "running" | "paused" | "completed" | "failed" | "cancelled";
+    current_step?: string;
+    started_at?: string;
+    completed_at?: string;
+    error_message?: string;
+}
+/**
+ * Step execution record
+ */
+export interface StepExecution {
+    id?: number;
+    run_id: number;
+    step_name: string;
+    step_index: number;
+    agent: string;
+    status: "pending" | "running" | "completed" | "failed" | "skipped";
+    retry_count?: number;
+    started_at?: string;
+    completed_at?: string;
+    error_message?: string;
+    output_path?: string;
+}
+/**
+ * Metric record
+ */
+export interface Metric {
+    id?: number;
+    run_id: number;
+    step_id?: number;
+    metric_name: string;
+    metric_value: number;
+    recorded_at?: string;
+}
+/**
+ * Database client wrapper
+ */
+export declare class OboraDatabase {
+    private db;
+    private connection;
+    private dbPath;
+    private initialized;
+    constructor(dbPath?: string);
+    /**
+     * Initialize database schema
+     */
+    initialize(): Promise<void>;
+    /**
+     * Execute a SQL query without returning results
+     */
+    run(sql: string, params?: any[]): Promise<void>;
+    /**
+     * Execute a SQL query and return all rows
+     */
+    query(sql: string, params?: any[]): Promise<any[]>;
+    /**
+     * Execute a SQL query and return first row
+     */
+    queryOne(sql: string, params?: any[]): Promise<any | null>;
+    /**
+     * Close database connection
+     */
+    close(): void;
+    /**
+     * Get database path
+     */
+    getPath(): string;
+}
+/**
+ * Insert a new project
+ */
+export declare function insertProject(db: OboraDatabase, project: Omit<Project, "id" | "created_at" | "updated_at">): Promise<number>;
+/**
+ * Get a project by ID
+ */
+export declare function getProject(db: OboraDatabase, id: number): Promise<Project | null>;
+/**
+ * Get a project by path
+ */
+export declare function getProjectByPath(db: OboraDatabase, projectPath: string): Promise<Project | null>;
+/**
+ * List all projects
+ */
+export declare function listProjects(db: OboraDatabase): Promise<Project[]>;
+/**
+ * Update a project
+ */
+export declare function updateProject(db: OboraDatabase, id: number, updates: Partial<Project>): Promise<void>;
+/**
+ * Delete a project
+ */
+export declare function deleteProject(db: OboraDatabase, id: number): Promise<void>;
+/**
+ * Insert a new workflow run
+ */
+export declare function insertWorkflowRun(db: OboraDatabase, run: Omit<WorkflowRun, "id" | "started_at">): Promise<number>;
+/**
+ * Get a workflow run by ID
+ */
+export declare function getWorkflowRun(db: OboraDatabase, id: number): Promise<WorkflowRun | null>;
+/**
+ * List workflow runs for a project
+ */
+export declare function listWorkflowRuns(db: OboraDatabase, projectId: number): Promise<WorkflowRun[]>;
+/**
+ * Update workflow run status
+ */
+export declare function updateWorkflowRunStatus(db: OboraDatabase, id: number, status: WorkflowRun["status"], currentStep?: string, errorMessage?: string): Promise<void>;
+/**
+ * Delete a workflow run
+ */
+export declare function deleteWorkflowRun(db: OboraDatabase, id: number): Promise<void>;
+/**
+ * Insert a new step execution
+ */
+export declare function insertStepExecution(db: OboraDatabase, step: Omit<StepExecution, "id" | "started_at">): Promise<number>;
+/**
+ * Get a step execution by ID
+ */
+export declare function getStepExecution(db: OboraDatabase, id: number): Promise<StepExecution | null>;
+/**
+ * List step executions for a run
+ */
+export declare function listStepExecutions(db: OboraDatabase, runId: number): Promise<StepExecution[]>;
+/**
+ * Update step execution status
+ */
+export declare function updateStepExecutionStatus(db: OboraDatabase, id: number, status: StepExecution["status"], output?: string, errorMessage?: string): Promise<void>;
+/**
+ * Increment retry count for a step
+ */
+export declare function incrementStepRetry(db: OboraDatabase, id: number): Promise<void>;
+/**
+ * Delete step executions for a run
+ */
+export declare function deleteStepExecutions(db: OboraDatabase, runId: number): Promise<void>;
+/**
+ * Insert a new metric
+ */
+export declare function insertMetric(db: OboraDatabase, metric: Omit<Metric, "id" | "recorded_at">): Promise<number>;
+/**
+ * Get metrics for a run
+ */
+export declare function getMetricsForRun(db: OboraDatabase, runId: number): Promise<Metric[]>;
+/**
+ * Get metrics for a specific step
+ */
+export declare function getMetricsForStep(db: OboraDatabase, stepId: number): Promise<Metric[]>;
+/**
+ * Aggregate metric value for a run
+ */
+export declare function aggregateMetric(db: OboraDatabase, runId: number, metricName: string, aggregate?: "SUM" | "AVG" | "MIN" | "MAX" | "COUNT"): Promise<number | null>;
+/**
+ * Delete metrics for a run
+ */
+export declare function deleteMetrics(db: OboraDatabase, runId: number): Promise<void>;

package/dist/_legacy/workflow/errors/diagnosis.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Actionable diagnosis templates for high-frequency errors
+ * Each template follows: Hypothesis → Evidence → Command → Rollback
+ * @module @obora/core/errors/diagnosis
+ */
+export interface DiagnosisTemplate {
+    /** Error code */
+    code: string;
+    /** One-line summary */
+    title: string;
+    /** Probable cause hypothesis */
+    hypothesis: string;
+    /** How to confirm the hypothesis */
+    evidence: string;
+    /** Command(s) to fix */
+    commands: string[];
+    /** How to undo if the fix makes things worse */
+    rollback: string;
+}
+/**
+ * Get diagnosis template for a given error code.
+ * Returns undefined if no template exists.
+ */
+export declare function getDiagnosis(code: string): DiagnosisTemplate | undefined;
+/**
+ * Format a diagnosis template as a human-readable CLI string.
+ */
+export declare function formatDiagnosis(diag: DiagnosisTemplate): string;
+/**
+ * Get all registered diagnosis templates.
+ */
+export declare function getAllDiagnoses(): DiagnosisTemplate[];

package/dist/_legacy/workflow/errors/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Error codes and classes for obora-kit
+ * @module @obora/core/errors
+ */
+/**
+ * Error codes mapping
+ * Reference: docs/spec/10-error-codes.md
+ */
+export declare const ErrorCodes: {
+    readonly E1001: "Unknown error";
+    readonly E1002: "Configuration not found";
+    readonly E1003: "Permission denied";
+    readonly E2001: "Invalid YAML syntax";
+    readonly E2002: "Missing required field";
+    readonly E2003: "Invalid field type";
+    readonly E2004: "Unknown field";
+    readonly E2005: "Invalid duration format";
+    readonly E2006: "Duplicate step name";
+    readonly E3001: "Circular dependency detected";
+    readonly E3002: "Missing dependency";
+    readonly E3003: "Self dependency";
+    readonly E3004: "Unresolved input file";
+    readonly E4001: "Step execution failed";
+    readonly E4002: "Timeout exceeded";
+    readonly E4003: "Agent not found";
+    readonly E4004: "Lock acquisition failed";
+    readonly E4005: "Step failed after retries exhausted";
+    readonly E4006: "Spec validation failed";
+    readonly E4007: "Context assembly failed";
+    readonly E6003: "OpenClaw connection failed";
+};
+export type ErrorCode = keyof typeof ErrorCodes;
+/**
+ * Base error class for obora-kit
+ */
+export declare class OboraError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: ErrorCode, message?: string, details?: Record<string, unknown>);
+}
+/**
+ * YAML parsing error
+ */
+export declare class ParseError extends OboraError {
+    constructor(code: ErrorCode, message?: string, details?: Record<string, unknown>);
+}
+/**
+ * Dependency resolution error
+ */
+export declare class DependencyError extends OboraError {
+    constructor(code: ErrorCode, message?: string, details?: Record<string, unknown>);
+}

package/dist/_legacy/workflow/graph/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Graph utilities for dependency resolution
+ * @module @obora/core/graph
+ */
+import type { Step } from "../types/workflow.js";
+/**
+ * Graph representation using adjacency list
+ */
+export interface Graph {
+    /** Set of all node names */
+    nodes: Set<string>;
+    /** Edge map: node -> set of dependent nodes (forward direction) */
+    edges: Map<string, Set<string>>;
+    /** Reverse edge map: node -> set of nodes this node depends on */
+    reverseEdges: Map<string, Set<string>>;
+}
+/**
+ * Result of cycle detection
+ */
+export interface CycleResult {
+    /** Whether a cycle exists */
+    hasCycle: boolean;
+    /** The path that forms the cycle (if any) */
+    cyclePath?: string[];
+}
+/**
+ * Result of topological sort
+ */
+export interface TopologicalResult {
+    /** Whether sort was successful (no cycles) */
+    success: boolean;
+    /** Sorted node names in execution order */
+    order: string[];
+    /** Cycle path if cycle detected */
+    cyclePath?: string[];
+}
+/**
+ * Build a graph from steps
+ */
+export declare function buildGraph(steps: Step[]): Graph;
+/**
+ * Detect cycles using DFS
+ */
+export declare function detectCycles(graph: Graph): CycleResult;
+/**
+ * Topological sort using Kahn's Algorithm
+ */
+export declare function topologicalSort(graph: Graph): TopologicalResult;
+/**
+ * Compute execution levels for each node
+ * Level 0 = no dependencies, Level N = depends on nodes up to level N-1
+ */
+export declare function computeLevels(graph: Graph): Map<string, number>;
+/**
+ * Group nodes by execution level
+ */
+export declare function groupByLevel(steps: Step[]): Map<number, Step[]>;

package/dist/_legacy/workflow/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./utils.js";
+export * from "./types/workflow.js";
+export * from "./errors/index.js";
+export * from "./errors/diagnosis.js";
+export * from "./parser/workflow-parser.js";
+export * from "./graph/index.js";
+export * from "./validator/workflow-validator.js";
+export { ValidationErrorCode } from "./validator/workflow-validator.js";
+export * from "./resolver/dependency-resolver.js";

package/dist/_legacy/workflow/parser/workflow-parser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Workflow YAML parser
+ * @module @obora/core/parser/workflow-parser
+ */
+import type { DependencyMap, ParserOptions, Workflow } from "../types/workflow.js";
+/**
+ * Parse workflow YAML string into typed Workflow object
+ */
+export declare function parseWorkflow(yamlContent: string, options?: ParserOptions): Workflow;
+/**
+ * Resolve dependencies including implicit ones from inputs/outputs
+ */
+export declare function resolveDependencies(workflow: Workflow): DependencyMap;

package/dist/_legacy/workflow/resolver/dependency-resolver.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Dependency resolver using Kahn's Algorithm
+ * @module @obora/core/resolver/dependency-resolver
+ */
+import { type CycleResult } from "../graph/index.js";
+import type { Step, Workflow } from "../types/workflow.js";
+/**
+ * Step group at a specific execution level
+ */
+export interface StepGroup {
+    /** Execution level (0 = no dependencies, 1+ = depends on earlier levels) */
+    level: number;
+    /** Steps that can be executed in parallel at this level */
+    steps: Step[];
+    /** Whether steps in this group can be executed in parallel */
+    parallelizable: boolean;
+}
+/**
+ * Execution plan for a workflow
+ */
+export interface ExecutionPlan {
+    /** Whether the plan is valid (no cycles) */
+    isValid: boolean;
+    /** Execution order of step names */
+    executionOrder: string[];
+    /** Cyclic dependency path (if any) */
+    cyclicPath?: string[];
+    /** Steps grouped by execution level */
+    stepGroups: StepGroup[];
+    /** Conditional back-edges (source -> target) */
+    backEdges: Array<{
+        source: string;
+        target: string;
+    }>;
+    /** Non-fatal planning warnings */
+    warnings: string[];
+}
+/**
+ * Dependency graph representation
+ */
+export interface DependencyGraph {
+    /** Map of step name to Step object */
+    nodes: Map<string, Step>;
+    /** Map of step name to list of dependency step names */
+    edges: Map<string, string[]>;
+    /** Conditional back-edges (source -> target) */
+    backEdges: Map<string, string>;
+}
+/**
+ * Build dependency graph from steps
+ */
+export declare function buildDependencyGraph(steps: Step[]): DependencyGraph;
+/**
+ * Resolve execution order using topological sort (Kahn's Algorithm)
+ */
+export declare function resolveTopologicalOrder(steps: Step[]): string[] | null;
+/**
+ * Check for cycles using DFS
+ */
+export declare function detectCyclesDFS(steps: Step[]): CycleResult;
+/**
+ * Calculate execution levels using BFS
+ */
+export declare function calculateExecutionLevels(steps: Step[]): Map<string, number>;
+/**
+ * Group steps by execution level
+ */
+export declare function groupStepsByLevel(steps: Step[]): StepGroup[];
+/**
+ * Generate full execution plan
+ */
+export declare function generateExecutionPlan(workflow: Workflow): ExecutionPlan;
+/**
+ * Get next executable steps from current execution state
+ */
+export declare function getNextSteps(workflow: Workflow, completedSteps: Set<string>): Step[];
+/**
+ * Validate execution order
+ */
+export declare function validateExecutionOrder(workflow: Workflow, order: string[]): {
+    valid: boolean;
+    errors: string[];
+};