@hilbras/omninode 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1036 @@
+import { z } from 'zod';
+
+/** Role system: what an AI is supposed to do, independent of any provider (§11). */
+interface RoleDefinition {
+    /** Slug identifier, e.g. "architecture-reviewer". */
+    id: string;
+    name: string;
+    description?: string;
+    responsibilities: string[];
+    /** What the role is expected to return, e.g. findings, evidence, recommendations. */
+    expectedOutputs: string[];
+    /** Optional hint; roles remain provider- and agent-independent. */
+    preferredAgents?: string[];
+    systemPrompt?: string;
+    metadata?: Record<string, unknown>;
+}
+
+/** Agent abstraction: CLI agents and custom agents plug in via adapters (§9–§10). */
+
+type AgentIntegrationType = "native" | "process" | "custom";
+type AgentStatus = "registered" | "ready" | "running" | "busy" | "stopped" | "error";
+interface AgentConfig {
+    name: string;
+    integration: AgentIntegrationType;
+    /** Executable command for process agents, e.g. "opencode". */
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Models (as "provider:model-id") this agent may use, if restricted. */
+    allowedModels?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface AgentInfo {
+    name: string;
+    integration: AgentIntegrationType;
+    version?: string;
+    capabilities?: string[];
+    command?: string;
+    cwd?: string;
+    status: AgentStatus;
+    metadata?: Record<string, unknown>;
+}
+interface AgentTaskInput {
+    taskId: string;
+    objective: string;
+    role?: RoleDefinition;
+    /** Assembled task context (project, memory, files) already selected for this agent. */
+    context?: string;
+    instruction?: string;
+}
+interface AgentTaskOutput {
+    taskId: string;
+    status: "completed" | "failed" | "cancelled";
+    summary?: string;
+    /** Verbatim agent output; structured report parsing lands in Phase 6. */
+    rawOutput?: string;
+    exitCode?: number;
+    logs?: string[];
+    error?: string;
+}
+/** Contract every agent adapter implements (Phase 3+). */
+interface IAgent {
+    readonly info: AgentInfo;
+    /** Submit a task and collect the agent's output. */
+    run(input: AgentTaskInput): Promise<AgentTaskOutput>;
+    /** Ask the agent to stop current work, if supported. */
+    cancel?(taskId: string): Promise<void>;
+}
+
+/** Chat completion types — the foundation for planner and research phases (§18, §15). */
+type ChatRole = "system" | "user" | "assistant";
+interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+interface ChatRequest {
+    /** Provider-specific model id, e.g. "qwen3-coder". */
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface ChatUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+}
+interface ChatResponse {
+    /** Model that actually served the request, as reported by the provider. */
+    model: string;
+    content: string;
+    finishReason?: string;
+    usage?: ChatUsage;
+    /** Verbatim provider response body for advanced consumers. */
+    raw?: unknown;
+}
+
+/**
+ * Memory abstraction. Remembera is the preferred Hilbras integration, but the
+ * core depends only on this interface (memory-agnostic principle, §2, §19).
+ */
+type MemoryScope = "project" | "role" | "task" | "knowledge";
+interface MemoryEntry {
+    key: string;
+    scope: MemoryScope;
+    content: string;
+    tags?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface MemoryQuery {
+    scope?: MemoryScope;
+    tags?: string[];
+    /** Free-text relevance query; implementations decide ranking. */
+    text?: string;
+    limit?: number;
+}
+interface IMemoryProvider {
+    readonly name: string;
+    /** Retrieve relevant memory; only relevant context should reach a task (§20). */
+    query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    write(entry: MemoryEntry): Promise<void>;
+}
+
+/** Normalized model registry entry (DEVELOPMENT_PLAN.md §8). */
+interface ModelCapabilities {
+    chat?: boolean;
+    coding?: boolean;
+    tools?: boolean;
+    vision?: boolean;
+    embeddings?: boolean;
+}
+type ModelStatus = "available" | "unavailable" | "deprecated";
+interface ModelInfo {
+    /** Name of the provider this model belongs to. */
+    provider: string;
+    /** Provider-specific model identifier, e.g. "qwen3-coder". */
+    id: string;
+    displayName?: string;
+    capabilities?: ModelCapabilities;
+    contextWindow?: number;
+    status?: ModelStatus;
+    metadata?: Record<string, unknown>;
+}
+
+/** Task system: every operation becomes a Task (§13). */
+type TaskStatus = "created" | "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled";
+interface TaskContext {
+    project?: string;
+    /** Paths or globs relevant to the task. */
+    files?: string[];
+    /** Free-form background injected into the prompt. */
+    background?: string;
+    /** Keys of memory entries pulled from the memory provider. */
+    memoryKeys?: string[];
+}
+interface TaskResult {
+    summary?: string;
+    artifacts?: string[];
+    reportId?: string;
+    error?: string;
+    finishedAt?: string;
+}
+interface Task {
+    id: string;
+    project?: string;
+    objective: string;
+    /** Role id from the role system. */
+    role?: string;
+    /** Agent name from the agent registry. */
+    agent?: string;
+    context?: TaskContext;
+    status: TaskStatus;
+    createdAt: string;
+    updatedAt: string;
+    result?: TaskResult;
+}
+
+/** Pipeline engine: coordinating multiple AI operations (§14). */
+
+type PipelineStepKind = "research" | "collect" | "analyze" | "plan" | "execute" | "custom";
+type PipelineStepCondition = "always" | "on-success" | "on-failure";
+interface PipelineStep {
+    id: string;
+    kind: PipelineStepKind;
+    /** Agents fanned out for research steps. */
+    agents?: string[];
+    /** Model used for plan steps, e.g. "my-gateway:chatgpt". */
+    model?: string;
+    dependsOn?: string[];
+    condition?: PipelineStepCondition;
+    retries?: number;
+}
+interface PipelineDefinition {
+    id: string;
+    name?: string;
+    steps: PipelineStep[];
+}
+type PipelineRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+interface PipelineStepRun {
+    stepId: string;
+    taskId?: string;
+    status: TaskStatus;
+}
+interface PipelineRun {
+    id: string;
+    pipelineId: string;
+    status: PipelineRunStatus;
+    startedAt?: string;
+    finishedAt?: string;
+    stepRuns: PipelineStepRun[];
+}
+
+/** Structured report format so reports can be processed programmatically (§16). */
+type Confidence = "low" | "medium" | "high";
+type FindingSeverity = "info" | "low" | "medium" | "high" | "critical";
+interface Finding {
+    id: string;
+    title: string;
+    detail: string;
+    severity?: FindingSeverity;
+    evidence?: string[];
+    /** File path or conceptual location the finding refers to. */
+    location?: string;
+    tags?: string[];
+}
+interface Report {
+    id: string;
+    taskId: string;
+    /** Agent name from the agent registry. */
+    agent: string;
+    /** Model id used, if known. */
+    model?: string;
+    summary: string;
+    findings: Finding[];
+    recommendations: string[];
+    confidence?: Confidence;
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+
+/** Agent ↔ OmniNode communication protocol (§21). */
+
+interface EnvelopeMeta {
+    taskId?: string;
+    agent?: string;
+    timestamp: string;
+    correlationId?: string;
+}
+type AgentToNodeMessage = {
+    type: "TASK_REQUEST";
+    payload: {
+        objective: string;
+        role?: string;
+    };
+} | {
+    type: "REPORT";
+    payload: Report;
+} | {
+    type: "STATUS";
+    payload: {
+        state: AgentStatus;
+        detail?: string;
+    };
+} | {
+    type: "QUESTION";
+    payload: {
+        question: string;
+    };
+} | {
+    type: "ARTIFACT";
+    payload: {
+        path: string;
+        description?: string;
+    };
+} | {
+    type: "COMPLETION";
+    payload: {
+        summary?: string;
+    };
+} | {
+    type: "ERROR";
+    payload: {
+        code: string;
+        message: string;
+    };
+};
+type NodeToAgentMessage = {
+    type: "TASK";
+    payload: {
+        taskId: string;
+        objective: string;
+    };
+} | {
+    type: "CONTEXT";
+    payload: {
+        body: string;
+    };
+} | {
+    type: "ROLE";
+    payload: RoleDefinition;
+} | {
+    type: "INSTRUCTION";
+    payload: {
+        text: string;
+    };
+}
+/** Plan schema lands in Phase 8. */
+ | {
+    type: "PLAN";
+    payload: unknown;
+} | {
+    type: "FEEDBACK";
+    payload: {
+        text: string;
+    };
+} | {
+    type: "VERIFICATION_RESULT";
+    payload: {
+        passed: boolean;
+        details?: string;
+    };
+};
+interface MessageEnvelope<T extends AgentToNodeMessage | NodeToAgentMessage> {
+    meta: EnvelopeMeta;
+    message: T;
+}
+
+/** Projects are first-class entities (§12). */
+interface Project {
+    name: string;
+    repository?: string;
+    workspace?: string;
+    agents: string[];
+    roles: string[];
+    providers?: string[];
+    memory?: {
+        provider: string;
+    };
+    createdAt?: string;
+}
+
+/**
+ * Provider abstraction. OmniNode is provider-agnostic: any AI gateway or local
+ * runtime plugs in through this interface (DEVELOPMENT_PLAN.md §5–§7).
+ */
+
+type ProviderType = "openai-compatible" | "omnihilbras" | "openrouter" | "local" | "custom";
+type ProviderHealth = "unknown" | "healthy" | "degraded" | "unreachable";
+interface ProviderConfig {
+    /** Unique name used in project configuration and the model registry. */
+    name: string;
+    type: ProviderType;
+    baseUrl: string;
+    /**
+     * Name of the environment variable that holds the API key. Keys are never
+     * stored in project files (DEVELOPMENT_PLAN.md §24 — Security).
+     */
+    apiKeyEnvVar?: string;
+    headers?: Record<string, string>;
+    enabled?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface ProviderStatus {
+    name: string;
+    type: ProviderType;
+    baseUrl: string;
+    health: ProviderHealth;
+    connected: boolean;
+    modelCount: number;
+    lastCheckedAt?: string;
+    message?: string;
+}
+/** Contract every provider adapter implements (Phase 1+). */
+interface IProvider {
+    readonly config: ProviderConfig;
+    /** Discover models exposed by this provider. */
+    listModels(): Promise<ModelInfo[]>;
+    /** Check connectivity and authentication. */
+    healthCheck(): Promise<ProviderStatus>;
+}
+/** Contract for providers that can run chat completions (foundation for planning). */
+interface IChatProvider extends IProvider {
+    chat(request: ChatRequest): Promise<ChatResponse>;
+}
+
+/** Typed error hierarchy shared across the whole codebase (§4.1 — error model). */
+type OmniNodeErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "PROVIDER_NOT_FOUND" | "PROVIDER_UNAVAILABLE" | "PROVIDER_AUTH_FAILED" | "MODEL_NOT_FOUND" | "AGENT_NOT_FOUND" | "AGENT_FAILED" | "AGENT_TIMEOUT" | "TASK_INVALID" | "TASK_FAILED" | "PIPELINE_INVALID" | "PIPELINE_FAILED" | "PROTOCOL_VIOLATION" | "MEMORY_UNAVAILABLE" | "NOT_IMPLEMENTED" | "CLI_USAGE" | "INTERNAL";
+interface OmniNodeErrorOptions {
+    cause?: unknown;
+    details?: Record<string, unknown>;
+}
+declare class OmniNodeError extends Error {
+    readonly code: OmniNodeErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: OmniNodeErrorCode, message: string, options?: OmniNodeErrorOptions);
+}
+declare class ConfigError extends OmniNodeError {
+    constructor(code: "CONFIG_NOT_FOUND" | "CONFIG_INVALID", message: string, options?: OmniNodeErrorOptions);
+}
+declare class ProviderError extends OmniNodeError {
+    constructor(code: "PROVIDER_NOT_FOUND" | "PROVIDER_UNAVAILABLE" | "PROVIDER_AUTH_FAILED" | "MODEL_NOT_FOUND", message: string, options?: OmniNodeErrorOptions);
+}
+declare class AgentError extends OmniNodeError {
+    constructor(code: "AGENT_NOT_FOUND" | "AGENT_FAILED" | "AGENT_TIMEOUT", message: string, options?: OmniNodeErrorOptions);
+}
+declare class TaskError extends OmniNodeError {
+    constructor(code: "TASK_INVALID" | "TASK_FAILED", message: string, options?: OmniNodeErrorOptions);
+}
+declare class PipelineError extends OmniNodeError {
+    constructor(code: "PIPELINE_INVALID" | "PIPELINE_FAILED", message: string, options?: OmniNodeErrorOptions);
+}
+declare class ProtocolError extends OmniNodeError {
+    constructor(message: string, options?: OmniNodeErrorOptions);
+}
+declare class MemoryError extends OmniNodeError {
+    constructor(message: string, options?: OmniNodeErrorOptions);
+}
+declare function isOmniNodeError(value: unknown): value is OmniNodeError;
+
+/** Leveled logger with a pluggable sink and child loggers (§4.1 — logging). */
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface LogSink {
+    write(level: LogLevel, line: string): void;
+}
+interface WritableLike {
+    write(chunk: string): unknown;
+}
+declare class ConsoleLogSink implements LogSink {
+    private readonly stream;
+    constructor(stream?: WritableLike);
+    write(_level: LogLevel, line: string): void;
+}
+interface LoggerOptions {
+    level?: LogLevel;
+    sink?: LogSink;
+    /** Structured fields attached to every line, e.g. { component: "config" }. */
+    context?: Record<string, unknown>;
+}
+declare class Logger {
+    private readonly level;
+    private readonly sink;
+    private readonly context;
+    constructor(options?: LoggerOptions);
+    child(context: Record<string, unknown>): Logger;
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    private log;
+}
+/** Default application logger. Writes to stderr so stdout stays clean for CLI output. */
+declare const logger: Logger;
+
+/**
+ * Configuration schema. The project file (omninode.yaml) uses snake_case keys
+ * as shown in DEVELOPMENT_PLAN.md §7 and §23; the loader maps them onto the
+ * camelCase TypeScript contracts in src/types.
+ */
+
+declare const providerConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<["openai-compatible", "omnihilbras", "openrouter", "local", "custom"]>;
+    base_url: z.ZodString;
+    api_key_env_var: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+    base_url: string;
+    api_key_env_var?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    enabled?: boolean | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    name: string;
+    type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+    base_url: string;
+    api_key_env_var?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    enabled?: boolean | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+declare const agentConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    /** "cli" agents communicate over stdin/stdout (process adapter). */
+    type: z.ZodDefault<z.ZodEnum<["cli", "native", "process"]>>;
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    type: "native" | "process" | "cli";
+    metadata?: Record<string, unknown> | undefined;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    name: string;
+    type?: "native" | "process" | "cli" | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+}>;
+declare const roleConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    responsibilities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    expected_outputs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    preferred_agents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    system_prompt: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    responsibilities: string[];
+    expected_outputs: string[];
+    metadata?: Record<string, unknown> | undefined;
+    description?: string | undefined;
+    preferred_agents?: string[] | undefined;
+    system_prompt?: string | undefined;
+}, {
+    name: string;
+    id: string;
+    metadata?: Record<string, unknown> | undefined;
+    description?: string | undefined;
+    responsibilities?: string[] | undefined;
+    expected_outputs?: string[] | undefined;
+    preferred_agents?: string[] | undefined;
+    system_prompt?: string | undefined;
+}>;
+declare const projectConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    providers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<["openai-compatible", "omnihilbras", "openrouter", "local", "custom"]>;
+        base_url: z.ZodString;
+        api_key_env_var: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+        base_url: string;
+        api_key_env_var?: string | undefined;
+        headers?: Record<string, string> | undefined;
+        enabled?: boolean | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        name: string;
+        type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+        base_url: string;
+        api_key_env_var?: string | undefined;
+        headers?: Record<string, string> | undefined;
+        enabled?: boolean | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }>, "many">>;
+    agents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        /** "cli" agents communicate over stdin/stdout (process adapter). */
+        type: z.ZodDefault<z.ZodEnum<["cli", "native", "process"]>>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        cwd: z.ZodOptional<z.ZodString>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        type: "native" | "process" | "cli";
+        metadata?: Record<string, unknown> | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        cwd?: string | undefined;
+        env?: Record<string, string> | undefined;
+    }, {
+        name: string;
+        type?: "native" | "process" | "cli" | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        cwd?: string | undefined;
+        env?: Record<string, string> | undefined;
+    }>, "many">>;
+    roles: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        responsibilities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        expected_outputs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        preferred_agents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        system_prompt: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        id: string;
+        responsibilities: string[];
+        expected_outputs: string[];
+        metadata?: Record<string, unknown> | undefined;
+        description?: string | undefined;
+        preferred_agents?: string[] | undefined;
+        system_prompt?: string | undefined;
+    }, {
+        name: string;
+        id: string;
+        metadata?: Record<string, unknown> | undefined;
+        description?: string | undefined;
+        responsibilities?: string[] | undefined;
+        expected_outputs?: string[] | undefined;
+        preferred_agents?: string[] | undefined;
+        system_prompt?: string | undefined;
+    }>, "many">>;
+    memory: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        provider: string;
+    }, {
+        provider: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    providers: {
+        name: string;
+        type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+        base_url: string;
+        api_key_env_var?: string | undefined;
+        headers?: Record<string, string> | undefined;
+        enabled?: boolean | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    agents: {
+        name: string;
+        type: "native" | "process" | "cli";
+        metadata?: Record<string, unknown> | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        cwd?: string | undefined;
+        env?: Record<string, string> | undefined;
+    }[];
+    roles: {
+        name: string;
+        id: string;
+        responsibilities: string[];
+        expected_outputs: string[];
+        metadata?: Record<string, unknown> | undefined;
+        description?: string | undefined;
+        preferred_agents?: string[] | undefined;
+        system_prompt?: string | undefined;
+    }[];
+    memory?: {
+        provider: string;
+    } | undefined;
+}, {
+    name: string;
+    providers?: {
+        name: string;
+        type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+        base_url: string;
+        api_key_env_var?: string | undefined;
+        headers?: Record<string, string> | undefined;
+        enabled?: boolean | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[] | undefined;
+    agents?: {
+        name: string;
+        type?: "native" | "process" | "cli" | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        cwd?: string | undefined;
+        env?: Record<string, string> | undefined;
+    }[] | undefined;
+    roles?: {
+        name: string;
+        id: string;
+        metadata?: Record<string, unknown> | undefined;
+        description?: string | undefined;
+        responsibilities?: string[] | undefined;
+        expected_outputs?: string[] | undefined;
+        preferred_agents?: string[] | undefined;
+        system_prompt?: string | undefined;
+    }[] | undefined;
+    memory?: {
+        provider: string;
+    } | undefined;
+}>;
+declare const appConfigSchema: z.ZodObject<{
+    project: z.ZodObject<{
+        name: z.ZodString;
+        providers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodEnum<["openai-compatible", "omnihilbras", "openrouter", "local", "custom"]>;
+            base_url: z.ZodString;
+            api_key_env_var: z.ZodOptional<z.ZodString>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+            base_url: string;
+            api_key_env_var?: string | undefined;
+            headers?: Record<string, string> | undefined;
+            enabled?: boolean | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }, {
+            name: string;
+            type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+            base_url: string;
+            api_key_env_var?: string | undefined;
+            headers?: Record<string, string> | undefined;
+            enabled?: boolean | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, "many">>;
+        agents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            /** "cli" agents communicate over stdin/stdout (process adapter). */
+            type: z.ZodDefault<z.ZodEnum<["cli", "native", "process"]>>;
+            command: z.ZodOptional<z.ZodString>;
+            args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            cwd: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            type: "native" | "process" | "cli";
+            metadata?: Record<string, unknown> | undefined;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            cwd?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }, {
+            name: string;
+            type?: "native" | "process" | "cli" | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            cwd?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        roles: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            responsibilities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            expected_outputs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            preferred_agents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            system_prompt: z.ZodOptional<z.ZodString>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            id: string;
+            responsibilities: string[];
+            expected_outputs: string[];
+            metadata?: Record<string, unknown> | undefined;
+            description?: string | undefined;
+            preferred_agents?: string[] | undefined;
+            system_prompt?: string | undefined;
+        }, {
+            name: string;
+            id: string;
+            metadata?: Record<string, unknown> | undefined;
+            description?: string | undefined;
+            responsibilities?: string[] | undefined;
+            expected_outputs?: string[] | undefined;
+            preferred_agents?: string[] | undefined;
+            system_prompt?: string | undefined;
+        }>, "many">>;
+        memory: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            provider: string;
+        }, {
+            provider: string;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        providers: {
+            name: string;
+            type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+            base_url: string;
+            api_key_env_var?: string | undefined;
+            headers?: Record<string, string> | undefined;
+            enabled?: boolean | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+        agents: {
+            name: string;
+            type: "native" | "process" | "cli";
+            metadata?: Record<string, unknown> | undefined;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            cwd?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[];
+        roles: {
+            name: string;
+            id: string;
+            responsibilities: string[];
+            expected_outputs: string[];
+            metadata?: Record<string, unknown> | undefined;
+            description?: string | undefined;
+            preferred_agents?: string[] | undefined;
+            system_prompt?: string | undefined;
+        }[];
+        memory?: {
+            provider: string;
+        } | undefined;
+    }, {
+        name: string;
+        providers?: {
+            name: string;
+            type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+            base_url: string;
+            api_key_env_var?: string | undefined;
+            headers?: Record<string, string> | undefined;
+            enabled?: boolean | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[] | undefined;
+        agents?: {
+            name: string;
+            type?: "native" | "process" | "cli" | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            cwd?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        roles?: {
+            name: string;
+            id: string;
+            metadata?: Record<string, unknown> | undefined;
+            description?: string | undefined;
+            responsibilities?: string[] | undefined;
+            expected_outputs?: string[] | undefined;
+            preferred_agents?: string[] | undefined;
+            system_prompt?: string | undefined;
+        }[] | undefined;
+        memory?: {
+            provider: string;
+        } | undefined;
+    }>;
+    logging: z.ZodOptional<z.ZodObject<{
+        level: z.ZodEnum<["debug", "info", "warn", "error"]>;
+    }, "strict", z.ZodTypeAny, {
+        level: "error" | "info" | "debug" | "warn";
+    }, {
+        level: "error" | "info" | "debug" | "warn";
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    project: {
+        name: string;
+        providers: {
+            name: string;
+            type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+            base_url: string;
+            api_key_env_var?: string | undefined;
+            headers?: Record<string, string> | undefined;
+            enabled?: boolean | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+        agents: {
+            name: string;
+            type: "native" | "process" | "cli";
+            metadata?: Record<string, unknown> | undefined;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            cwd?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[];
+        roles: {
+            name: string;
+            id: string;
+            responsibilities: string[];
+            expected_outputs: string[];
+            metadata?: Record<string, unknown> | undefined;
+            description?: string | undefined;
+            preferred_agents?: string[] | undefined;
+            system_prompt?: string | undefined;
+        }[];
+        memory?: {
+            provider: string;
+        } | undefined;
+    };
+    logging?: {
+        level: "error" | "info" | "debug" | "warn";
+    } | undefined;
+}, {
+    project: {
+        name: string;
+        providers?: {
+            name: string;
+            type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
+            base_url: string;
+            api_key_env_var?: string | undefined;
+            headers?: Record<string, string> | undefined;
+            enabled?: boolean | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[] | undefined;
+        agents?: {
+            name: string;
+            type?: "native" | "process" | "cli" | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            command?: string | undefined;
+            args?: string[] | undefined;
+            cwd?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        roles?: {
+            name: string;
+            id: string;
+            metadata?: Record<string, unknown> | undefined;
+            description?: string | undefined;
+            responsibilities?: string[] | undefined;
+            expected_outputs?: string[] | undefined;
+            preferred_agents?: string[] | undefined;
+            system_prompt?: string | undefined;
+        }[] | undefined;
+        memory?: {
+            provider: string;
+        } | undefined;
+    };
+    logging?: {
+        level: "error" | "info" | "debug" | "warn";
+    } | undefined;
+}>;
+type ProviderConfigYaml = z.infer<typeof providerConfigSchema>;
+type AgentConfigYaml = z.infer<typeof agentConfigSchema>;
+type RoleConfigYaml = z.infer<typeof roleConfigSchema>;
+type ProjectConfigYaml = z.infer<typeof projectConfigSchema>;
+type AppConfigYaml = z.infer<typeof appConfigSchema>;
+
+interface AppConfig {
+    project: {
+        name: string;
+        providers: ProviderConfig[];
+        agents: AgentConfig[];
+        roles: RoleDefinition[];
+        memory?: {
+            provider: string;
+        };
+    };
+    logging?: {
+        level: LogLevel;
+    };
+}
+interface LoadConfigOptions {
+    /** Explicit path; otherwise omninode.yaml/yml/json is looked up in the given directory. */
+    path?: string;
+    directory?: string;
+    /** Environment used for ${VAR} expansion; defaults to process.env. */
+    env?: Record<string, string | undefined>;
+}
+declare function findConfigFile(directory?: string): string | undefined;
+/**
+ * Replaces ${VAR} and ${VAR:-fallback} references. Unset variables without a
+ * fallback abort loading: a half-resolved config could silently misroute
+ * authentication.
+ */
+declare function expandEnvRefs(text: string, env: Record<string, string | undefined>, source?: string): string;
+declare function loadConfig(options?: LoadConfigOptions): AppConfig;
+
+/** Template written by `omninode init` (§22, §23). */
+declare function defaultProjectConfigYaml(projectName?: string): string;
+
+declare function resolveApiKey(config: ProviderConfig, env?: Record<string, string | undefined>): string | undefined;
+declare function authHeaders(config: ProviderConfig, env?: Record<string, string | undefined>): Record<string, string>;
+
+interface HttpRequestOptions {
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeoutMs?: number;
+}
+interface HttpResponse {
+    status: number;
+    body: unknown;
+}
+declare function requestJson(url: string, options?: HttpRequestOptions): Promise<HttpResponse>;
+
+/** Provider types served by the OpenAI-compatible adapter. */
+declare const OPENAI_COMPATIBLE_TYPES: readonly ProviderType[];
+declare function createProvider(config: ProviderConfig): IChatProvider;
+
+declare class OpenAICompatibleProvider implements IChatProvider {
+    readonly config: ProviderConfig;
+    private readonly log;
+    constructor(config: ProviderConfig, log?: Logger);
+    listModels(): Promise<ModelInfo[]>;
+    healthCheck(): Promise<ProviderStatus>;
+    chat(request: ChatRequest): Promise<ChatResponse>;
+}
+
+/**
+ * Normalized model registry (§8): aggregates models discovered from all
+ * configured providers under "provider:model" keys.
+ */
+
+interface ModelFilter {
+    provider?: string;
+    capability?: keyof ModelCapabilities;
+}
+interface DiscoveryResult {
+    provider: string;
+    models: ModelInfo[];
+    error?: Error;
+}
+declare function registryKey(provider: string, id: string): string;
+declare class ModelRegistry {
+    private readonly models;
+    register(model: ModelInfo): void;
+    get(provider: string, id: string): ModelInfo | undefined;
+    list(filter?: ModelFilter): ModelInfo[];
+    /** Availability validation (§27 Phase 1): present in the registry and not retired. */
+    isAvailable(provider: string, id: string): boolean;
+    /** Discover models from one provider and register them. */
+    discoverFrom(provider: IProvider): Promise<ModelInfo[]>;
+    /** Discover from many providers; a failing provider does not abort the rest. */
+    discoverAll(providers: IProvider[]): Promise<DiscoveryResult[]>;
+}
+
+declare const OMNINODE_VERSION = "0.2.0";
+
+export { type AgentConfig, type AgentConfigYaml, AgentError, type AgentInfo, type AgentIntegrationType, type AgentStatus, type AgentTaskInput, type AgentTaskOutput, type AgentToNodeMessage, type AppConfig, type AppConfigYaml, type ChatMessage, type ChatRequest, type ChatResponse, type ChatRole, type ChatUsage, type Confidence, ConfigError, ConsoleLogSink, type DiscoveryResult, type EnvelopeMeta, type Finding, type FindingSeverity, type HttpRequestOptions, type HttpResponse, type IAgent, type IChatProvider, type IMemoryProvider, type IProvider, type LoadConfigOptions, type LogLevel, type LogSink, Logger, type LoggerOptions, type MemoryEntry, MemoryError, type MemoryQuery, type MemoryScope, type MessageEnvelope, type ModelCapabilities, type ModelFilter, type ModelInfo, ModelRegistry, type ModelStatus, type NodeToAgentMessage, OMNINODE_VERSION, OPENAI_COMPATIBLE_TYPES, OmniNodeError, type OmniNodeErrorCode, type OmniNodeErrorOptions, OpenAICompatibleProvider, type PipelineDefinition, PipelineError, type PipelineRun, type PipelineRunStatus, type PipelineStep, type PipelineStepCondition, type PipelineStepKind, type PipelineStepRun, type Project, type ProjectConfigYaml, ProtocolError, type ProviderConfig, type ProviderConfigYaml, ProviderError, type ProviderHealth, type ProviderStatus, type ProviderType, type Report, type RoleConfigYaml, type RoleDefinition, type Task, type TaskContext, TaskError, type TaskResult, type TaskStatus, type WritableLike, agentConfigSchema, appConfigSchema, authHeaders, createProvider, defaultProjectConfigYaml, expandEnvRefs, findConfigFile, isOmniNodeError, loadConfig, logger, projectConfigSchema, providerConfigSchema, registryKey, requestJson, resolveApiKey, roleConfigSchema };