@hilbras/omninode 2.0.0-alpha.1 → 2.0.0-alpha.3

package/dist/index.d.ts

@@ -65,6 +65,99 @@ interface CombinedReport {
     metadata?: Record<string, unknown>;
 }
 
+/**
+ * OmniNode Agent Protocol v2 — message model (roadmap §7.2–§7.4, §7.7).
+ *
+ * Every message is a JSON line carrying a `ProtocolEnvelope`. All ids are
+ * optional for inbound tolerance but OmniNode always emits them, so every
+ * message is traceable to agent / task / pipeline / execution / request.
+ */
+
+/** Messages OmniNode sends to an agent. */
+type ProtocolNodeToAgentType = "TASK" | "HELLO_ACK" | "CONTEXT" | "INSTRUCTION" | "RESPONSE" | "CANCEL";
+/** Messages an agent sends to OmniNode. */
+type ProtocolAgentToNodeType = "HELLO" | "TASK_REQUEST" | "TASK_ACCEPTED" | "TASK_STARTED" | "STATUS" | "QUESTION" | "REPORT" | "ARTIFACT" | "COMPLETION" | "ERROR" | "CANCELLED";
+type ProtocolMessageType = ProtocolNodeToAgentType | ProtocolAgentToNodeType;
+interface ProtocolEnvelope<T extends ProtocolMessageType = ProtocolMessageType> {
+    /** `omninode-agent-protocol/2`. Inbound messages without it are treated as v1. */
+    protocol: string;
+    /** Unique id of this message. */
+    messageId: string;
+    /** Id of the request/thread this message belongs to. */
+    requestId?: string;
+    taskId?: string;
+    agentId?: string;
+    pipelineId?: string;
+    /** Execution identity (roadmap §6.5) — ties the message to one attempt. */
+    executionId?: string;
+    timestamp: string;
+    type: T;
+    payload: unknown;
+    metadata?: Record<string, unknown>;
+}
+/** Standard artifact kinds (roadmap §7.7). */
+type ArtifactKind = "file" | "patch" | "report" | "log" | "screenshot" | "document" | "data";
+interface ArtifactPayload {
+    kind: ArtifactKind;
+    /** Path, URL or logical name. */
+    ref: string;
+    description?: string;
+    mediaType?: string;
+    bytes?: number;
+    metadata?: Record<string, unknown>;
+}
+interface QuestionPayload {
+    /** Question id to answer. */
+    questionId: string;
+    question: string;
+    /** What kind of answer is expected (free text, file path, options…). */
+    expected?: "text" | "path" | "choice";
+    options?: string[];
+}
+interface TaskPayload {
+    taskId: string;
+    objective: string;
+}
+interface ReportPayload {
+    report: Report | Report[];
+}
+/** A question an agent asked during a run, with the answer OmniNode gave (if any). */
+interface AskedQuestion {
+    questionId: string;
+    question: string;
+    answer?: string;
+}
+declare function newMessageId(prefix?: string): string;
+/** Builds a v2 envelope with ids and timestamp filled in. */
+declare function envelope<T extends ProtocolMessageType>(type: T, payload: unknown, ids?: {
+    requestId?: string;
+    taskId?: string;
+    agentId?: string;
+    pipelineId?: string;
+    executionId?: string;
+    metadata?: Record<string, unknown>;
+}): ProtocolEnvelope<T>;
+
+interface AgentDescriptor {
+    /** Protocol the agent speaks. */
+    protocol: string;
+    name: string;
+    version?: string;
+    capabilities: string[];
+    /** Message types the agent can emit. */
+    supports: string[];
+}
+type HelloResult = {
+    ok: true;
+    descriptor: AgentDescriptor;
+} | {
+    ok: false;
+    reason: string;
+};
+declare function parseHello(envelopeValue: ProtocolEnvelope): HelloResult;
+declare function buildHello(descriptor: Omit<AgentDescriptor, "protocol">): ProtocolEnvelope<"HELLO">;
+declare function buildHelloAck(descriptor: AgentDescriptor): ProtocolEnvelope<"HELLO_ACK">;
+
 /** Role system: what an AI is supposed to do, independent of any provider (§11). */
 interface RoleDefinition {
     /** Slug identifier, e.g. "architecture-reviewer". */
@@ -117,6 +210,10 @@ interface AgentInfo {
 interface AgentTaskInput {
     taskId: string;
     objective: string;
+    /** Pipeline run that owns this task (protocol correlation, §7.4). */
+    pipelineId?: string;
+    /** Execution identity for this attempt (protocol correlation, §7.4). */
+    executionId?: string;
     role?: RoleDefinition;
     /** Assembled task context (project, memory, files) already selected for this agent. */
     context?: string;
@@ -132,6 +229,14 @@ interface AgentTaskOutput {
     logs?: string[];
     /** Structured reports extracted from protocol-mode runs (§16, §21). */
     reports?: Report[];
+    /** Protocol diagnostics for protocol-mode runs (roadmap §7): questions asked, violations seen. */
+    protocol?: {
+        protocol: string;
+        legacy: boolean;
+        descriptor?: AgentDescriptor;
+        questions: AskedQuestion[];
+        violations: string[];
+    };
     error?: string;
 }
 /** Contract every agent adapter implements (Phase 3+). */
@@ -229,7 +334,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. */
@@ -262,6 +387,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;
 }
 
@@ -292,7 +423,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;
@@ -585,18 +721,18 @@ declare const providerConfigSchema: z.ZodObject<{
     name: string;
     type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
     base_url: string;
+    metadata?: Record<string, unknown> | undefined;
     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;
+    metadata?: Record<string, unknown> | undefined;
     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;
@@ -613,7 +749,7 @@ declare const agentConfigSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     name: string;
     type: "native" | "process" | "cli";
-    input_mode: "stdin" | "arg" | "protocol";
+    input_mode: "protocol" | "stdin" | "arg";
     metadata?: Record<string, unknown> | undefined;
     command?: string | undefined;
     args?: string[] | undefined;
@@ -623,13 +759,13 @@ declare const agentConfigSchema: z.ZodObject<{
     inherit_env?: boolean | undefined;
 }, {
     name: string;
-    type?: "native" | "process" | "cli" | undefined;
     metadata?: Record<string, unknown> | undefined;
+    type?: "native" | "process" | "cli" | undefined;
     command?: string | undefined;
     args?: string[] | undefined;
     cwd?: string | undefined;
     env?: Record<string, string> | undefined;
-    input_mode?: "stdin" | "arg" | "protocol" | undefined;
+    input_mode?: "protocol" | "stdin" | "arg" | undefined;
     timeout_ms?: number | undefined;
     inherit_env?: boolean | undefined;
 }>;
@@ -734,8 +870,8 @@ declare const pipelineConfigSchema: z.ZodObject<{
         retries?: number | undefined;
         condition?: "always" | "on-success" | "on-failure" | undefined;
     }[];
-    role?: string | undefined;
     name?: string | undefined;
+    role?: string | undefined;
     objective?: string | undefined;
 }, {
     id: string;
@@ -749,8 +885,8 @@ declare const pipelineConfigSchema: z.ZodObject<{
         retries?: number | undefined;
         condition?: "always" | "on-success" | "on-failure" | undefined;
     }[];
-    role?: string | undefined;
     name?: string | undefined;
+    role?: string | undefined;
     objective?: string | undefined;
 }>;
 declare const plannerConfigSchema: z.ZodObject<{
@@ -780,18 +916,18 @@ declare const projectConfigSchema: z.ZodObject<{
         name: string;
         type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
         base_url: string;
+        metadata?: Record<string, unknown> | undefined;
         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;
+        metadata?: Record<string, unknown> | undefined;
         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;
@@ -808,7 +944,7 @@ declare const projectConfigSchema: z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         name: string;
         type: "native" | "process" | "cli";
-        input_mode: "stdin" | "arg" | "protocol";
+        input_mode: "protocol" | "stdin" | "arg";
         metadata?: Record<string, unknown> | undefined;
         command?: string | undefined;
         args?: string[] | undefined;
@@ -818,13 +954,13 @@ declare const projectConfigSchema: z.ZodObject<{
         inherit_env?: boolean | undefined;
     }, {
         name: string;
-        type?: "native" | "process" | "cli" | undefined;
         metadata?: Record<string, unknown> | undefined;
+        type?: "native" | "process" | "cli" | undefined;
         command?: string | undefined;
         args?: string[] | undefined;
         cwd?: string | undefined;
         env?: Record<string, string> | undefined;
-        input_mode?: "stdin" | "arg" | "protocol" | undefined;
+        input_mode?: "protocol" | "stdin" | "arg" | undefined;
         timeout_ms?: number | undefined;
         inherit_env?: boolean | undefined;
     }>, "many">>;
@@ -901,8 +1037,8 @@ declare const projectConfigSchema: z.ZodObject<{
             retries?: number | undefined;
             condition?: "always" | "on-success" | "on-failure" | undefined;
         }[];
-        role?: string | undefined;
         name?: string | undefined;
+        role?: string | undefined;
         objective?: string | undefined;
     }, {
         id: string;
@@ -916,8 +1052,8 @@ declare const projectConfigSchema: z.ZodObject<{
             retries?: number | undefined;
             condition?: "always" | "on-success" | "on-failure" | undefined;
         }[];
-        role?: string | undefined;
         name?: string | undefined;
+        role?: string | undefined;
         objective?: string | undefined;
     }>, "many">>;
     planner: z.ZodOptional<z.ZodObject<{
@@ -951,7 +1087,7 @@ declare const projectConfigSchema: z.ZodObject<{
     agents: {
         name: string;
         type: "native" | "process" | "cli";
-        input_mode: "stdin" | "arg" | "protocol";
+        input_mode: "protocol" | "stdin" | "arg";
         metadata?: Record<string, unknown> | undefined;
         command?: string | undefined;
         args?: string[] | undefined;
@@ -964,10 +1100,10 @@ declare const projectConfigSchema: z.ZodObject<{
         name: string;
         type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
         base_url: string;
+        metadata?: Record<string, unknown> | undefined;
         api_key_env_var?: string | undefined;
         headers?: Record<string, string> | undefined;
         enabled?: boolean | undefined;
-        metadata?: Record<string, unknown> | undefined;
     }[];
     roles: {
         name: string;
@@ -991,8 +1127,8 @@ declare const projectConfigSchema: z.ZodObject<{
             retries?: number | undefined;
             condition?: "always" | "on-success" | "on-failure" | undefined;
         }[];
-        role?: string | undefined;
         name?: string | undefined;
+        role?: string | undefined;
         objective?: string | undefined;
     }[];
     planner?: {
@@ -1009,13 +1145,13 @@ declare const projectConfigSchema: z.ZodObject<{
     name: string;
     agents?: {
         name: string;
-        type?: "native" | "process" | "cli" | undefined;
         metadata?: Record<string, unknown> | undefined;
+        type?: "native" | "process" | "cli" | undefined;
         command?: string | undefined;
         args?: string[] | undefined;
         cwd?: string | undefined;
         env?: Record<string, string> | undefined;
-        input_mode?: "stdin" | "arg" | "protocol" | undefined;
+        input_mode?: "protocol" | "stdin" | "arg" | undefined;
         timeout_ms?: number | undefined;
         inherit_env?: boolean | undefined;
     }[] | undefined;
@@ -1023,10 +1159,10 @@ declare const projectConfigSchema: z.ZodObject<{
         name: string;
         type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
         base_url: string;
+        metadata?: Record<string, unknown> | undefined;
         api_key_env_var?: string | undefined;
         headers?: Record<string, string> | undefined;
         enabled?: boolean | undefined;
-        metadata?: Record<string, unknown> | undefined;
     }[] | undefined;
     roles?: {
         name: string;
@@ -1050,8 +1186,8 @@ declare const projectConfigSchema: z.ZodObject<{
             retries?: number | undefined;
             condition?: "always" | "on-success" | "on-failure" | undefined;
         }[];
-        role?: string | undefined;
         name?: string | undefined;
+        role?: string | undefined;
         objective?: string | undefined;
     }[] | undefined;
     planner?: {
@@ -1080,18 +1216,18 @@ declare const appConfigSchema: z.ZodObject<{
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             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;
+            metadata?: Record<string, unknown> | undefined;
             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;
@@ -1108,7 +1244,7 @@ declare const appConfigSchema: z.ZodObject<{
         }, "strict", z.ZodTypeAny, {
             name: string;
             type: "native" | "process" | "cli";
-            input_mode: "stdin" | "arg" | "protocol";
+            input_mode: "protocol" | "stdin" | "arg";
             metadata?: Record<string, unknown> | undefined;
             command?: string | undefined;
             args?: string[] | undefined;
@@ -1118,13 +1254,13 @@ declare const appConfigSchema: z.ZodObject<{
             inherit_env?: boolean | undefined;
         }, {
             name: string;
-            type?: "native" | "process" | "cli" | undefined;
             metadata?: Record<string, unknown> | undefined;
+            type?: "native" | "process" | "cli" | undefined;
             command?: string | undefined;
             args?: string[] | undefined;
             cwd?: string | undefined;
             env?: Record<string, string> | undefined;
-            input_mode?: "stdin" | "arg" | "protocol" | undefined;
+            input_mode?: "protocol" | "stdin" | "arg" | undefined;
             timeout_ms?: number | undefined;
             inherit_env?: boolean | undefined;
         }>, "many">>;
@@ -1201,8 +1337,8 @@ declare const appConfigSchema: z.ZodObject<{
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }, {
             id: string;
@@ -1216,8 +1352,8 @@ declare const appConfigSchema: z.ZodObject<{
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }>, "many">>;
         planner: z.ZodOptional<z.ZodObject<{
@@ -1251,7 +1387,7 @@ declare const appConfigSchema: z.ZodObject<{
         agents: {
             name: string;
             type: "native" | "process" | "cli";
-            input_mode: "stdin" | "arg" | "protocol";
+            input_mode: "protocol" | "stdin" | "arg";
             metadata?: Record<string, unknown> | undefined;
             command?: string | undefined;
             args?: string[] | undefined;
@@ -1264,10 +1400,10 @@ declare const appConfigSchema: z.ZodObject<{
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             api_key_env_var?: string | undefined;
             headers?: Record<string, string> | undefined;
             enabled?: boolean | undefined;
-            metadata?: Record<string, unknown> | undefined;
         }[];
         roles: {
             name: string;
@@ -1291,8 +1427,8 @@ declare const appConfigSchema: z.ZodObject<{
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }[];
         planner?: {
@@ -1309,13 +1445,13 @@ declare const appConfigSchema: z.ZodObject<{
         name: string;
         agents?: {
             name: string;
-            type?: "native" | "process" | "cli" | undefined;
             metadata?: Record<string, unknown> | undefined;
+            type?: "native" | "process" | "cli" | undefined;
             command?: string | undefined;
             args?: string[] | undefined;
             cwd?: string | undefined;
             env?: Record<string, string> | undefined;
-            input_mode?: "stdin" | "arg" | "protocol" | undefined;
+            input_mode?: "protocol" | "stdin" | "arg" | undefined;
             timeout_ms?: number | undefined;
             inherit_env?: boolean | undefined;
         }[] | undefined;
@@ -1323,10 +1459,10 @@ declare const appConfigSchema: z.ZodObject<{
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             api_key_env_var?: string | undefined;
             headers?: Record<string, string> | undefined;
             enabled?: boolean | undefined;
-            metadata?: Record<string, unknown> | undefined;
         }[] | undefined;
         roles?: {
             name: string;
@@ -1350,8 +1486,8 @@ declare const appConfigSchema: z.ZodObject<{
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }[] | undefined;
         planner?: {
@@ -1378,7 +1514,7 @@ declare const appConfigSchema: z.ZodObject<{
         agents: {
             name: string;
             type: "native" | "process" | "cli";
-            input_mode: "stdin" | "arg" | "protocol";
+            input_mode: "protocol" | "stdin" | "arg";
             metadata?: Record<string, unknown> | undefined;
             command?: string | undefined;
             args?: string[] | undefined;
@@ -1391,10 +1527,10 @@ declare const appConfigSchema: z.ZodObject<{
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             api_key_env_var?: string | undefined;
             headers?: Record<string, string> | undefined;
             enabled?: boolean | undefined;
-            metadata?: Record<string, unknown> | undefined;
         }[];
         roles: {
             name: string;
@@ -1418,8 +1554,8 @@ declare const appConfigSchema: z.ZodObject<{
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }[];
         planner?: {
@@ -1441,13 +1577,13 @@ declare const appConfigSchema: z.ZodObject<{
         name: string;
         agents?: {
             name: string;
-            type?: "native" | "process" | "cli" | undefined;
             metadata?: Record<string, unknown> | undefined;
+            type?: "native" | "process" | "cli" | undefined;
             command?: string | undefined;
             args?: string[] | undefined;
             cwd?: string | undefined;
             env?: Record<string, string> | undefined;
-            input_mode?: "stdin" | "arg" | "protocol" | undefined;
+            input_mode?: "protocol" | "stdin" | "arg" | undefined;
             timeout_ms?: number | undefined;
             inherit_env?: boolean | undefined;
         }[] | undefined;
@@ -1455,10 +1591,10 @@ declare const appConfigSchema: z.ZodObject<{
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             api_key_env_var?: string | undefined;
             headers?: Record<string, string> | undefined;
             enabled?: boolean | undefined;
-            metadata?: Record<string, unknown> | undefined;
         }[] | undefined;
         roles?: {
             name: string;
@@ -1482,8 +1618,8 @@ declare const appConfigSchema: z.ZodObject<{
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }[] | undefined;
         planner?: {
@@ -1668,6 +1804,104 @@ declare function createAgent(config: AgentConfig): IAgent;
 /** Builds an agent registry from the project configuration, skipping agents that fail to construct. */
 declare function buildAgentRegistry(config: AppConfig, log?: Logger): AgentRegistry;
 
+/**
+ * OmniNode Agent Protocol v2 — versioning (roadmap §7.1).
+ *
+ * Protocol identifiers are namespaced strings so an agent can negotiate the
+ * dialect it speaks: `omninode-agent-protocol/2`.
+ */
+declare const PROTOCOL_V2 = "omninode-agent-protocol/2";
+/** Versions this build accepts. v1 is the unversioned dialect shipped with OmniNode 1.x. */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+declare const MAX_MESSAGE_BYTES = 1048576;
+declare function isSupportedProtocol(protocol: string): boolean;
+
+type ProtocolViolationCode = "INVALID_JSON" | "NOT_AN_OBJECT" | "UNKNOWN_TYPE" | "MISSING_FIELD" | "UNSUPPORTED_VERSION" | "OVERSIZED" | "INVALID_PAYLOAD";
+interface ProtocolViolation {
+    code: ProtocolViolationCode;
+    message: string;
+    /** Raw line (truncated) for diagnostics. */
+    sample?: string;
+}
+type DecodeResult = {
+    ok: true;
+    envelope: ProtocolEnvelope;
+    legacy: boolean;
+} | {
+    ok: false;
+    error: ProtocolViolation;
+};
+/** Validates one decoded JSON value as a protocol envelope. */
+declare function validateEnvelope(value: unknown, line?: string): DecodeResult;
+/** Decodes one protocol line (no trailing newline). */
+declare function decodeMessage(line: string, maxBytes?: number): DecodeResult;
+/** Serializes an envelope to a single JSON line. */
+declare function encodeMessage(envelope: ProtocolEnvelope, maxBytes?: number): string;
+/**
+ * Streaming line decoder for agent stdout. Feed chunks; receive decoded
+ * envelopes and violations in order. Survives garbage: a bad line yields a
+ * violation and the stream continues.
+ */
+declare class ProtocolDecoder {
+    private buffer;
+    private readonly maxBytes;
+    constructor(maxBytes?: number);
+    push(chunk: string): DecodeResult[];
+    /** Flush any trailing line when the process exits. */
+    flush(): DecodeResult[];
+}
+
+/**
+ * OmniNode Agent Protocol v2 — session (roadmap §7.6).
+ *
+ * A session drives a protocol-mode agent: it emits v2 envelopes with
+ * correlation ids, tolerates legacy (unversioned) replies, answers agent
+ * questions through a responder callback, and collects reports, artifacts
+ * and the completion — never throwing on malformed input.
+ */
+
+interface SessionIds {
+    requestId: string;
+    taskId: string;
+    agentId: string;
+    pipelineId?: string;
+    executionId?: string;
+}
+interface QuestionResponder {
+    (question: {
+        questionId: string;
+        question: string;
+        expected?: string;
+    }): Promise<string> | string;
+}
+declare class ProtocolSession {
+    readonly decoder: ProtocolDecoder;
+    private readonly ids;
+    private readonly responder;
+    readonly violations: ProtocolViolation[];
+    readonly questions: AskedQuestion[];
+    readonly artifacts: ProtocolEnvelope["payload"][];
+    reports: ProtocolEnvelope["payload"][];
+    descriptor?: AgentDescriptor;
+    completionSummary?: string;
+    errorMessage?: string;
+    constructor(ids: SessionIds, options?: {
+        responder?: QuestionResponder;
+        maxBytes?: number;
+    });
+    /** The v2 messages OmniNode sends to open a task (written to the agent's stdin). */
+    taskMessages(objective: string, role?: unknown, context?: string, instruction?: string): string[];
+    helloAck(descriptor: AgentDescriptor): string;
+    /** Consumes decoded stdout, answering questions as they arrive. */
+    handle(decoded: DecodeResult): Promise<void>;
+    private answerQuestion;
+    readonly pendingAnswers: string[];
+    /** True once any inbound message carried the v2 protocol field. */
+    sawV2: boolean;
+}
+declare function decodeStream(session: ProtocolSession, chunk: string): Promise<string[]>;
+declare function requireCompletion(session: ProtocolSession): void;
+
 /** Role registry (§11): the set of roles available for task assignment. */
 
 declare class RoleRegistry {
@@ -1823,6 +2057,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;
@@ -1840,10 +2080,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[]>;
@@ -2111,6 +2353,6 @@ declare class ProjectStores {
     constructor(directory?: string);
 }
 
-declare const OMNINODE_VERSION = "2.0.0-alpha.1";
+declare const OMNINODE_VERSION = "2.0.0-alpha.3";
 
-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, 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, 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 };
+export { type AgentConfig, type AgentConfigYaml, type AgentDescriptor, 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 ArtifactKind, type ArtifactPayload, type AskedQuestion, 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 DecodeResult, type DiscoveryResult, type EnvelopeMeta, type ExecutionRecord, type ExtractionMeta, FileAuditLog, FilePipelineRunStore, FilePlanStore, FileReportStore, FileTaskStore, type Finding, type FindingSeverity, type FindingSource, type HelloResult, 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, MAX_MESSAGE_BYTES, 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, PROTOCOL_V2, 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, type ProtocolAgentToNodeType, ProtocolDecoder, type ProtocolEnvelope, ProtocolError, type ProtocolMessageType, type ProtocolNodeToAgentType, ProtocolSession, type ProtocolViolation, type ProtocolViolationCode, type ProviderConfig, type ProviderConfigYaml, ProviderError, type ProviderHealth, type ProviderStatus, type ProviderType, type QuestionPayload, type QuestionResponder, type RememberaConfig, RememberaMemoryProvider, type Report, type ReportFilter, type ReportPayload, ReportService, type ReportStore, type RoleConfigYaml, type RoleDefinition, RoleRegistry, type RunPipelineOptions, SUPPORTED_PROTOCOL_VERSIONS, type SessionIds, TERMINAL_TASK_STATUSES, type Task, type TaskContext, TaskEngine, type TaskEngineOptions, TaskError, type TaskPayload, type TaskResult, type TaskStatus, type TaskStore, type TaskStoreFilter, type WritableLike, agentConfigSchema, aggregateReports, appConfigSchema, authHeaders, buildAgentRegistry, buildChildEnv, buildHello, buildHelloAck, buildPipelineEngine, buildPlanner, buildPlannerContext, buildRoleRegistry, composeTaskText, createAgent, createDefaultChatFn, createMemoryProvider, createProvider, createTaskEngine, decodeMessage, decodeStream, defaultProjectConfigYaml, encodeMessage, envelope, expandEnvRefs, extractReportFromText, findConfigFile, isOmniNodeError, isSupportedProtocol, keywords, loadConfig, logger, newMessageId, parseHello, parsePlanJson, pipelineConfigSchema, pipelineStepConfigSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, registryKey, requestJson, requireCompletion, resolveApiKey, roleConfigSchema, similar, validateEnvelope };