@hilbras/omninode 1.0.0 → 2.0.0-alpha.2

package/dist/index.d.ts

@@ -172,6 +172,11 @@ interface ChatResponse {
     /** Verbatim provider response body for advanced consumers. */
     raw?: unknown;
 }
+/**
+ * Model-backed chat used by the planner layer. Lives in the neutral types
+ * layer so adapters (e.g. planner) never depend on engine modules.
+ */
+type ChatFn = (model: string, messages: ChatMessage[]) => Promise<string>;
 
 /**
  * Memory abstraction. Remembera is the preferred Hilbras integration, but the
@@ -224,7 +229,27 @@ interface ModelInfo {
 
 /** Task system: every operation becomes a Task (§13). */
 
-type TaskStatus = "created" | "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled";
+/**
+ * Execution states (v2 Phase 2, roadmap §6.1).
+ *
+ * The crucial distinction: `unknown` means "we cannot prove the outcome" —
+ * e.g. a process timeout after the agent may already have performed side
+ * effects. It is deliberately NOT `failed`: retrying blindly could duplicate
+ * work, and reporting failure would be a lie. Resolve it explicitly with
+ * `task retry` (which starts a fresh execution) or by inspecting artifacts.
+ */
+type TaskStatus = "created" | "queued" | "running" | "waiting" | "completed" | "failed" | "timed_out" | "cancelled" | "unknown" | "partially_completed";
+/** States from which no further automatic transition happens. */
+declare const TERMINAL_TASK_STATUSES: readonly TaskStatus[];
+/** One execution attempt (roadmap §6.5 identity: task + attempt + execution id). */
+interface ExecutionRecord {
+    executionId: string;
+    attempt: number;
+    startedAt: string;
+    finishedAt: string;
+    outcome: "completed" | "failed" | "timed_out" | "unknown" | "cancelled";
+    error?: string;
+}
 interface TaskContext {
     project?: string;
     /** Paths or globs relevant to the task. */
@@ -257,6 +282,12 @@ interface Task {
     status: TaskStatus;
     createdAt: string;
     updatedAt: string;
+    /** Number of engine.run attempts so far (0 = never executed). */
+    attempt: number;
+    /** Error from the most recent failed/unknown attempt. */
+    lastError?: string;
+    /** Recent execution attempts, newest last, bounded in length. */
+    executions?: ExecutionRecord[];
     result?: TaskResult;
 }
 
@@ -287,7 +318,12 @@ interface PipelineDefinition {
     role?: string;
     steps: PipelineStep[];
 }
-type PipelineRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+/**
+ * Run status. "partial" means the run finished but some step outcome was
+ * incomplete or unprovable (partial fan-out, unknown task state) — the
+ * authoritative detail always lives in `stepRuns`/`taskRuns`.
+ */
+type PipelineRunStatus = "pending" | "running" | "completed" | "failed" | "partial" | "cancelled";
 interface PipelineStepRun {
     stepId: string;
     status: TaskStatus;
@@ -1625,6 +1661,13 @@ declare class OmniHilbrasProvider extends OpenAICompatibleProvider {
     connect(registry?: ModelRegistry): Promise<OmniHilbrasConnectionResult>;
 }
 
+/**
+ * Builds the child environment. By default the agent inherits the full
+ * environment; with `inheritEnv: false` it receives only PATH plus the
+ * explicitly configured variables — useful to avoid leaking OmniNode's
+ * own secrets (e.g. provider API keys) into third-party agents.
+ */
+declare function buildChildEnv(config: AgentConfig): NodeJS.ProcessEnv;
 declare function composeTaskText(input: AgentTaskInput): string;
 declare class ProcessAgent implements IAgent {
     readonly config: AgentConfig;
@@ -1668,6 +1711,41 @@ declare class RoleRegistry {
 /** Builds a role registry from the project configuration. */
 declare function buildRoleRegistry(config: AppConfig): RoleRegistry;
 
+interface JsonDocument<T> {
+    /** Bumped when the persisted shape changes in a breaking way (v2 Phase 12). */
+    schemaVersion?: number;
+    items: T[];
+}
+interface JsonFileStoreOptions {
+    directory?: string;
+    fileName: string;
+    schemaVersion?: number;
+    /** Called when a persisted file cannot be parsed. */
+    onCorrupt?: (path: string, error: unknown) => void;
+}
+declare class JsonFileStore<T> {
+    private readonly filePath;
+    private readonly schemaVersion;
+    private readonly onCorrupt?;
+    private readonly log;
+    private queue;
+    constructor(options: JsonFileStoreOptions);
+    get path(): string;
+    /** All items, or [] when missing/corrupt. */
+    protected readAll(): Promise<T[]>;
+    protected writeAll(items: T[]): Promise<void>;
+    /** Serializes an async operation against this file. */
+    protected synchronized<R>(operation: () => Promise<R>): Promise<R>;
+    /** Read-modify-write helper: applies `mutate` to the current items. */
+    protected mutate<R>(mutate: (items: T[]) => Promise<[T[], R]> | [T[], R]): Promise<R>;
+}
+
+/**
+ * Task persistence (§4.1 — execution state). The store is replaceable
+ * (§2 — Modular); the default implementation is a local JSON file so
+ * OmniNode stays local-first (§25).
+ */
+
 interface TaskStoreFilter {
     status?: TaskStatus;
     project?: string;
@@ -1677,20 +1755,11 @@ interface TaskStore {
     get(id: string): Promise<Task | undefined>;
     list(filter?: TaskStoreFilter): Promise<Task[]>;
 }
-declare class FileTaskStore implements TaskStore {
-    private readonly filePath;
-    /**
-     * Read-modify-write operations are serialized: parallel pipeline tasks
-     * would otherwise race on the JSON file (last writer wins).
-     */
-    private queue;
+declare class FileTaskStore extends JsonFileStore<Task> implements TaskStore {
     constructor(directory?: string);
     save(task: Task): Promise<void>;
     get(id: string): Promise<Task | undefined>;
     list(filter?: TaskStoreFilter): Promise<Task[]>;
-    private synchronized;
-    private load;
-    private write;
 }
 
 type AuditAction = "task.created" | "task.queued" | "task.running" | "task.completed" | "task.failed" | "task.cancelled" | "task.retry" | "pipeline.run.started" | "pipeline.run.finished" | "plan.generated" | "memory.context.gathered" | "memory.outcome.recorded";
@@ -1715,18 +1784,20 @@ declare class FileAuditLog implements AuditSink {
     recent(limit?: number): Promise<AuditEvent[]>;
 }
 
+/**
+ * Local file-based memory provider: the default implementation so persistent
+ * memory works out of the box, locally (§25), with no external service.
+ * Relevance is scored by keyword overlap and tag matches — deterministic and
+ * dependency-free.
+ */
+
 declare function keywords(text: string): Set<string>;
-declare class LocalMemoryProvider implements IMemoryProvider {
+declare class LocalMemoryProvider extends JsonFileStore<MemoryEntry> implements IMemoryProvider {
     readonly name = "local";
-    private readonly filePath;
-    private queue;
     constructor(directory?: string);
     query(query: MemoryQuery): Promise<MemoryEntry[]>;
     write(entry: MemoryEntry): Promise<void>;
     count(): Promise<number>;
-    private synchronized;
-    private load;
-    private saveAll;
 }
 
 interface RememberaConfig {
@@ -1783,6 +1854,12 @@ interface CreateTaskInput {
     agent?: string;
     context?: TaskContext;
 }
+interface RunTaskOptions {
+    /** Total attempts (1 = no automatic retry). Retries apply to retryable errors only. */
+    maxAttempts?: number;
+    /** Linear backoff base in ms: waits backoffMs × attempt between attempts. */
+    retryBackoffMs?: number;
+}
 interface TaskEngineOptions {
     agents: AgentRegistry;
     roles: RoleRegistry;
@@ -1800,10 +1877,12 @@ declare class TaskEngine {
     get store(): TaskStore;
     create(input: CreateTaskInput): Promise<Task>;
     queue(id: string): Promise<Task>;
-    /** Runs the task through its assigned agent and records the result. */
-    run(id: string): Promise<Task>;
+    /** Runs the task through its assigned agent and records the result.
+     *  `maxAttempts` enables bounded automatic retries of *retryable* errors
+     *  with linear backoff; unknown/timed_out outcomes are never auto-retried. */
+    run(id: string, options?: RunTaskOptions): Promise<Task>;
     cancel(id: string): Promise<Task>;
-    /** Error recovery (§27 Phase 9): reset a failed/cancelled task so it can run again. */
+    /** Error recovery: reset a failed/cancelled/unknown/timed_out task so it can run again. */
     retry(id: string): Promise<Task>;
     get(id: string): Promise<Task | undefined>;
     list(filter?: TaskStoreFilter): Promise<Task[]>;
@@ -1816,6 +1895,11 @@ declare class TaskEngine {
 
 declare function createTaskEngine(config: AppConfig, log?: Logger, directory?: string): TaskEngine;
 
+/**
+ * Report persistence (§16 — report storage). Same replaceable-store and
+ * serialized-write patterns as the other local stores.
+ */
+
 interface ReportFilter {
     taskId?: string;
     agent?: string;
@@ -1830,18 +1914,20 @@ interface ReportStore {
     getCombined(id: string): Promise<CombinedReport | undefined>;
     listCombined(filter?: CombinedReportFilter): Promise<CombinedReport[]>;
 }
-declare class FileReportStore implements ReportStore {
-    private readonly filePath;
-    private queue;
+type StoreEntry = {
+    kind: "report";
+    report: Report;
+} | {
+    kind: "combined";
+    combined: CombinedReport;
+};
+declare class FileReportStore extends JsonFileStore<StoreEntry> implements ReportStore {
     constructor(directory?: string);
     saveReports(reports: Report[]): Promise<void>;
     listReports(filter?: ReportFilter): Promise<Report[]>;
     saveCombined(combined: CombinedReport): Promise<void>;
     getCombined(id: string): Promise<CombinedReport | undefined>;
     listCombined(filter?: CombinedReportFilter): Promise<CombinedReport[]>;
-    private synchronized;
-    private load;
-    private write;
 }
 
 /**
@@ -1909,6 +1995,50 @@ interface IPlanner {
     plan(request: PlanRequest): Promise<Plan>;
 }
 
+/**
+ * Planner context builder (§18): assembles everything the planner needs —
+ * the objective, the combined findings from the AI reports (with source
+ * attribution), relevant memory and the role definition — into one
+ * structured text.
+ */
+
+declare function buildPlannerContext(request: PlanRequest): string;
+
+declare class HeuristicPlanner implements IPlanner {
+    readonly name = "heuristic";
+    plan(request: PlanRequest): Promise<Plan>;
+}
+
+interface ModelPlannerOptions {
+    model: string;
+    chat: ChatFn;
+    /** Extra instruction appended to the system prompt. */
+    instruction?: string;
+    /** Used when the model output is unparseable (or the call fails, if tolerateErrors). */
+    fallback?: IPlanner;
+    log?: Logger;
+}
+declare class ModelPlanner implements IPlanner {
+    private readonly options;
+    readonly name = "model";
+    private readonly log;
+    constructor(options: ModelPlannerOptions);
+    plan(request: PlanRequest): Promise<Plan>;
+    private degrade;
+}
+/** Extracts and validates the plan JSON from arbitrary model output. */
+declare function parsePlanJson(text: string): {
+    summary: string;
+    steps: PlanStep[];
+    risks?: string[];
+    notes?: string[];
+} | undefined;
+
+/**
+ * Plan persistence (§27 Phase 8 — planner result storage). Same
+ * replaceable-store pattern as the other local stores.
+ */
+
 interface PlanFilter {
     pipelineRunId?: string;
     taskId?: string;
@@ -1918,6 +2048,19 @@ interface PlanStore {
     get(id: string): Promise<Plan | undefined>;
     list(filter?: PlanFilter): Promise<Plan[]>;
 }
+declare class FilePlanStore extends JsonFileStore<Plan> implements PlanStore {
+    constructor(directory?: string);
+    save(plan: Plan): Promise<void>;
+    get(id: string): Promise<Plan | undefined>;
+    list(filter?: PlanFilter): Promise<Plan[]>;
+}
+
+declare function buildPlanner(plannerConfig: AppConfig["project"]["planner"], chat: ChatFn, log?: Logger): IPlanner | undefined;
+
+/**
+ * Pipeline run persistence (§27 Phase 5 — pipeline state). Same
+ * replaceable-store pattern as the task store, local-first JSON file.
+ */
 
 interface PipelineRunFilter {
     pipelineId?: string;
@@ -1928,19 +2071,13 @@ interface PipelineRunStore {
     get(id: string): Promise<PipelineRun | undefined>;
     list(filter?: PipelineRunFilter): Promise<PipelineRun[]>;
 }
-declare class FilePipelineRunStore implements PipelineRunStore {
-    private readonly filePath;
-    private queue;
+declare class FilePipelineRunStore extends JsonFileStore<PipelineRun> implements PipelineRunStore {
     constructor(directory?: string);
     save(run: PipelineRun): Promise<void>;
     get(id: string): Promise<PipelineRun | undefined>;
     list(filter?: PipelineRunFilter): Promise<PipelineRun[]>;
-    private synchronized;
-    private load;
-    private write;
 }
 
-type ChatFn = (modelRef: string, messages: ChatMessage[]) => Promise<string>;
 interface PipelineEngineOptions {
     tasks: TaskEngine;
     agents: AgentRegistry;
@@ -1994,6 +2131,25 @@ declare function createDefaultChatFn(providers: AppConfig["project"]["providers"
 
 declare function buildPipelineEngine(config: AppConfig, log?: Logger): PipelineEngine;
 
-declare const OMNINODE_VERSION = "1.0.0";
+/**
+ * Persistence layer (v2 Phase 1): one entry point to every local store.
+ *
+ * All stores are interfaces with a local JSON default
+ * (TaskStore, PipelineRunStore, ReportStore, PlanStore, IMemoryProvider,
+ * AuditSink) — see docs/API.md for the inventory and stability status.
+ */
+
+/** Bundles every store for a single project directory. */
+declare class ProjectStores {
+    readonly tasks: FileTaskStore;
+    readonly pipelineRuns: FilePipelineRunStore;
+    readonly reports: FileReportStore;
+    readonly plans: FilePlanStore;
+    readonly memory: LocalMemoryProvider;
+    readonly audit: FileAuditLog;
+    constructor(directory?: string);
+}
+
+declare const OMNINODE_VERSION = "2.0.0-alpha.2";
 
-export { type AgentConfig, type AgentConfigYaml, AgentError, type AgentInfo, type AgentInputMode, type AgentIntegrationType, AgentRegistry, type AgentStatus, type AgentTaskInput, type AgentTaskOutput, type AgentToNodeMessage, type AggregateOptions, type AggregatedFinding, type AggregatedRecommendation, type AppConfig, type AppConfigYaml, type AuditAction, type AuditEvent, type AuditSink, type ChatFn, type ChatMessage, type ChatRequest, type ChatResponse, type ChatRole, type ChatUsage, type CombinedMeta, type CombinedReport, type CombinedReportFilter, type Confidence, ConfigError, ConsoleLogSink, type CreateTaskInput, type DiscoveryResult, type EnvelopeMeta, type ExtractionMeta, FileAuditLog, FilePipelineRunStore, FileReportStore, FileTaskStore, type Finding, type FindingSeverity, type FindingSource, type HttpRequestOptions, type HttpResponse, type IAgent, type IChatProvider, type IMemoryProvider, type IProvider, type LoadConfigOptions, LocalMemoryProvider, type LogLevel, type LogSink, Logger, type LoggerOptions, type MemoryContextQuery, type MemoryEntry, MemoryError, type MemoryProviderConfig, type MemoryQuery, type MemoryScope, MemoryService, type MessageEnvelope, type ModelCapabilities, type ModelFilter, type ModelInfo, ModelRegistry, type ModelStatus, type NodeToAgentMessage, OMNINODE_VERSION, OPENAI_COMPATIBLE_TYPES, type OmniHilbrasConnectionResult, OmniHilbrasProvider, OmniNodeError, type OmniNodeErrorCode, type OmniNodeErrorOptions, OpenAICompatibleProvider, type PipelineConfigYaml, type PipelineDefinition, PipelineEngine, type PipelineEngineOptions, PipelineError, type PipelineRun, type PipelineRunFilter, type PipelineRunStatus, type PipelineRunStore, type PipelineStep, type PipelineStepCondition, type PipelineStepConfigYaml, type PipelineStepKind, type PipelineStepRun, type Plan, type PlanStep, type PlannerConfigYaml, PlannerError, ProcessAgent, type Project, type ProjectConfigYaml, ProtocolError, type ProviderConfig, type ProviderConfigYaml, ProviderError, type ProviderHealth, type ProviderStatus, type ProviderType, type RememberaConfig, RememberaMemoryProvider, type Report, type ReportFilter, ReportService, type ReportStore, type RoleConfigYaml, type RoleDefinition, RoleRegistry, type RunPipelineOptions, type Task, type TaskContext, TaskEngine, type TaskEngineOptions, TaskError, type TaskResult, type TaskStatus, type TaskStore, type TaskStoreFilter, type WritableLike, agentConfigSchema, aggregateReports, appConfigSchema, authHeaders, buildAgentRegistry, buildPipelineEngine, buildRoleRegistry, composeTaskText, createAgent, createDefaultChatFn, createMemoryProvider, createProvider, createTaskEngine, defaultProjectConfigYaml, expandEnvRefs, extractReportFromText, findConfigFile, isOmniNodeError, keywords, loadConfig, logger, pipelineConfigSchema, pipelineStepConfigSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, registryKey, requestJson, resolveApiKey, roleConfigSchema, similar };
+export { type AgentConfig, type AgentConfigYaml, AgentError, type AgentInfo, type AgentInputMode, type AgentIntegrationType, AgentRegistry, type AgentStatus, type AgentTaskInput, type AgentTaskOutput, type AgentToNodeMessage, type AggregateOptions, type AggregatedFinding, type AggregatedRecommendation, type AppConfig, type AppConfigYaml, type AuditAction, type AuditEvent, type AuditSink, type ChatFn, type ChatMessage, type ChatRequest, type ChatResponse, type ChatRole, type ChatUsage, type CombinedMeta, type CombinedReport, type CombinedReportFilter, type Confidence, ConfigError, ConsoleLogSink, type CreateTaskInput, type DiscoveryResult, type EnvelopeMeta, type ExecutionRecord, type ExtractionMeta, FileAuditLog, FilePipelineRunStore, FilePlanStore, FileReportStore, FileTaskStore, type Finding, type FindingSeverity, type FindingSource, HeuristicPlanner, type HttpRequestOptions, type HttpResponse, type IAgent, type IChatProvider, type IMemoryProvider, type IPlanner, type IProvider, type JsonDocument, JsonFileStore, type JsonFileStoreOptions, type LoadConfigOptions, LocalMemoryProvider, type LogLevel, type LogSink, Logger, type LoggerOptions, type MemoryContextQuery, type MemoryEntry, MemoryError, type MemoryProviderConfig, type MemoryQuery, type MemoryScope, MemoryService, type MessageEnvelope, type ModelCapabilities, type ModelFilter, type ModelInfo, ModelPlanner, ModelRegistry, type ModelStatus, type NodeToAgentMessage, OMNINODE_VERSION, OPENAI_COMPATIBLE_TYPES, type OmniHilbrasConnectionResult, OmniHilbrasProvider, OmniNodeError, type OmniNodeErrorCode, type OmniNodeErrorOptions, OpenAICompatibleProvider, type PipelineConfigYaml, type PipelineDefinition, PipelineEngine, type PipelineEngineOptions, PipelineError, type PipelineRun, type PipelineRunFilter, type PipelineRunStatus, type PipelineRunStore, type PipelineStep, type PipelineStepCondition, type PipelineStepConfigYaml, type PipelineStepKind, type PipelineStepRun, type Plan, type PlanFilter, type PlanRequest, type PlanStep, type PlanStore, type PlannerConfigYaml, PlannerError, ProcessAgent, type Project, type ProjectConfigYaml, ProjectStores, ProtocolError, type ProviderConfig, type ProviderConfigYaml, ProviderError, type ProviderHealth, type ProviderStatus, type ProviderType, type RememberaConfig, RememberaMemoryProvider, type Report, type ReportFilter, ReportService, type ReportStore, type RoleConfigYaml, type RoleDefinition, RoleRegistry, type RunPipelineOptions, TERMINAL_TASK_STATUSES, type Task, type TaskContext, TaskEngine, type TaskEngineOptions, TaskError, type TaskResult, type TaskStatus, type TaskStore, type TaskStoreFilter, type WritableLike, agentConfigSchema, aggregateReports, appConfigSchema, authHeaders, buildAgentRegistry, buildChildEnv, buildPipelineEngine, buildPlanner, buildPlannerContext, buildRoleRegistry, composeTaskText, createAgent, createDefaultChatFn, createMemoryProvider, createProvider, createTaskEngine, defaultProjectConfigYaml, expandEnvRefs, extractReportFromText, findConfigFile, isOmniNodeError, keywords, loadConfig, logger, parsePlanJson, pipelineConfigSchema, pipelineStepConfigSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, registryKey, requestJson, resolveApiKey, roleConfigSchema, similar };