@hilbras/omninode 2.0.0-alpha.2 → 2.0.0-alpha.4

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { ChildProcess } from 'node:child_process';
 
 /** Structured report format so reports can be processed programmatically (§16). */
 type Confidence = "low" | "medium" | "high";
@@ -65,6 +66,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". */
@@ -98,8 +192,21 @@ interface AgentConfig {
     inputMode?: AgentInputMode;
     /** Per-task timeout in milliseconds; the process is killed when exceeded. */
     timeoutMs?: number;
-    /** When false, the agent process starts with a minimal environment (PATH + env). */
+    /**
+     * When false, the agent process starts with a minimal environment (PATH +
+     * env). Deprecated in v2 — prefer `envPolicy`.
+     */
     inheritEnv?: boolean;
+    /** Explicit environment policy (roadmap §8). */
+    envPolicy?: "inherit" | "allowlist" | "denylist" | "explicit";
+    /** Variables forwarded from the parent under the `allowlist` policy. */
+    envAllowlist?: string[];
+    /** Variables removed from the parent under the `denylist` policy. */
+    envDenylist?: string[];
+    /** Per-stream byte budget for agent stdout/stderr (default 5 MiB). */
+    maxOutputBytes?: number;
+    /** Allow a working directory outside the project root. */
+    allowExternalCwd?: boolean;
     /** Models (as "provider:model-id") this agent may use, if restricted. */
     allowedModels?: string[];
     metadata?: Record<string, unknown>;
@@ -117,6 +224,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 +243,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+). */
@@ -616,18 +735,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;
@@ -640,11 +759,16 @@ declare const agentConfigSchema: z.ZodObject<{
     input_mode: z.ZodDefault<z.ZodEnum<["stdin", "arg", "protocol"]>>;
     timeout_ms: z.ZodOptional<z.ZodNumber>;
     inherit_env: z.ZodOptional<z.ZodBoolean>;
+    env_policy: z.ZodOptional<z.ZodEnum<["inherit", "allowlist", "denylist", "explicit"]>>;
+    env_allowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    env_denylist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    max_output_bytes: z.ZodOptional<z.ZodNumber>;
+    allow_external_cwd: z.ZodOptional<z.ZodBoolean>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "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;
@@ -652,17 +776,27 @@ declare const agentConfigSchema: z.ZodObject<{
     env?: Record<string, string> | undefined;
     timeout_ms?: number | undefined;
     inherit_env?: boolean | undefined;
+    env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+    env_allowlist?: string[] | undefined;
+    env_denylist?: string[] | undefined;
+    max_output_bytes?: number | undefined;
+    allow_external_cwd?: 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;
+    env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+    env_allowlist?: string[] | undefined;
+    env_denylist?: string[] | undefined;
+    max_output_bytes?: number | undefined;
+    allow_external_cwd?: boolean | undefined;
 }>;
 declare const roleConfigSchema: z.ZodObject<{
     id: z.ZodString;
@@ -765,8 +899,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;
@@ -780,8 +914,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<{
@@ -811,18 +945,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;
@@ -835,11 +969,16 @@ declare const projectConfigSchema: z.ZodObject<{
         input_mode: z.ZodDefault<z.ZodEnum<["stdin", "arg", "protocol"]>>;
         timeout_ms: z.ZodOptional<z.ZodNumber>;
         inherit_env: z.ZodOptional<z.ZodBoolean>;
+        env_policy: z.ZodOptional<z.ZodEnum<["inherit", "allowlist", "denylist", "explicit"]>>;
+        env_allowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env_denylist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        max_output_bytes: z.ZodOptional<z.ZodNumber>;
+        allow_external_cwd: z.ZodOptional<z.ZodBoolean>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "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;
@@ -847,17 +986,27 @@ declare const projectConfigSchema: z.ZodObject<{
         env?: Record<string, string> | undefined;
         timeout_ms?: number | undefined;
         inherit_env?: boolean | undefined;
+        env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+        env_allowlist?: string[] | undefined;
+        env_denylist?: string[] | undefined;
+        max_output_bytes?: number | undefined;
+        allow_external_cwd?: 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;
+        env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+        env_allowlist?: string[] | undefined;
+        env_denylist?: string[] | undefined;
+        max_output_bytes?: number | undefined;
+        allow_external_cwd?: boolean | undefined;
     }>, "many">>;
     roles: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -932,8 +1081,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;
@@ -947,8 +1096,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<{
@@ -982,7 +1131,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;
@@ -990,15 +1139,20 @@ declare const projectConfigSchema: z.ZodObject<{
         env?: Record<string, string> | undefined;
         timeout_ms?: number | undefined;
         inherit_env?: boolean | undefined;
+        env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+        env_allowlist?: string[] | undefined;
+        env_denylist?: string[] | undefined;
+        max_output_bytes?: number | undefined;
+        allow_external_cwd?: boolean | undefined;
     }[];
     providers: {
         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;
@@ -1022,8 +1176,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?: {
@@ -1040,24 +1194,29 @@ 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;
+        env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+        env_allowlist?: string[] | undefined;
+        env_denylist?: string[] | undefined;
+        max_output_bytes?: number | undefined;
+        allow_external_cwd?: boolean | undefined;
     }[] | undefined;
     providers?: {
         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;
@@ -1081,8 +1240,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?: {
@@ -1111,18 +1270,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;
@@ -1135,11 +1294,16 @@ declare const appConfigSchema: z.ZodObject<{
             input_mode: z.ZodDefault<z.ZodEnum<["stdin", "arg", "protocol"]>>;
             timeout_ms: z.ZodOptional<z.ZodNumber>;
             inherit_env: z.ZodOptional<z.ZodBoolean>;
+            env_policy: z.ZodOptional<z.ZodEnum<["inherit", "allowlist", "denylist", "explicit"]>>;
+            env_allowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            env_denylist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            max_output_bytes: z.ZodOptional<z.ZodNumber>;
+            allow_external_cwd: z.ZodOptional<z.ZodBoolean>;
             metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, "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;
@@ -1147,17 +1311,27 @@ declare const appConfigSchema: z.ZodObject<{
             env?: Record<string, string> | undefined;
             timeout_ms?: number | undefined;
             inherit_env?: boolean | undefined;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: 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;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }>, "many">>;
         roles: z.ZodDefault<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -1232,8 +1406,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;
@@ -1247,8 +1421,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<{
@@ -1282,7 +1456,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;
@@ -1290,15 +1464,20 @@ declare const appConfigSchema: z.ZodObject<{
             env?: Record<string, string> | undefined;
             timeout_ms?: number | undefined;
             inherit_env?: boolean | undefined;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }[];
         providers: {
             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;
@@ -1322,8 +1501,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?: {
@@ -1340,24 +1519,29 @@ 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;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }[] | undefined;
         providers?: {
             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;
@@ -1381,8 +1565,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?: {
@@ -1409,7 +1593,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;
@@ -1417,15 +1601,20 @@ declare const appConfigSchema: z.ZodObject<{
             env?: Record<string, string> | undefined;
             timeout_ms?: number | undefined;
             inherit_env?: boolean | undefined;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }[];
         providers: {
             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;
@@ -1449,8 +1638,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?: {
@@ -1472,24 +1661,29 @@ 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;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }[] | undefined;
         providers?: {
             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;
@@ -1513,8 +1707,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?: {
@@ -1662,12 +1856,21 @@ declare class OmniHilbrasProvider extends OpenAICompatibleProvider {
 }
 
 /**
- * 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.
+ * Process adapter (§9): runs CLI agents as child processes and communicates
+ * over stdin/stdout, managing the process lifecycle, working directory,
+ * environment, exit codes, logs and timeouts.
+ *
+ * Three input modes (§9, §21):
+ *  - "stdin":    the composed task text is written to the agent's stdin.
+ *  - "arg":      the composed task text is appended as the last command argument.
+ *  - "protocol": NodeToAgentMessage envelopes as JSON lines on stdin; the
+ *                agent answers with AgentToNodeMessage JSON lines (REPORT,
+ *                COMPLETION, ERROR, ...) whose structured payloads are parsed
+ *                into reports.
  */
-declare function buildChildEnv(config: AgentConfig): NodeJS.ProcessEnv;
+
+/** Per-stream byte budget before output is truncated and the agent killed. */
+declare const DEFAULT_MAX_OUTPUT_BYTES: number;
 declare function composeTaskText(input: AgentTaskInput): string;
 declare class ProcessAgent implements IAgent {
     readonly config: AgentConfig;
@@ -1680,6 +1883,63 @@ declare class ProcessAgent implements IAgent {
     cancel(taskId: string): Promise<void>;
     runningTaskIds(): string[];
 }
+/** Kills a child and, on POSIX, its whole process group (roadmap §8 tree cleanup). */
+declare function killTree(child: ChildProcess, signal: NodeJS.Signals): void;
+/** Human-readable exit reason, including signal terminations. */
+declare function describeExit(code: number | null, signal: NodeJS.Signals | null): string;
+/**
+ * Decodes a stdout/stderr chunk safely: invalid UTF-8 becomes replacement
+ * characters and NUL bytes are stripped, so binary noise cannot poison the
+ * protocol decoder or the terminal (roadmap §8, encoding hardening).
+ */
+declare function sanitizeChunk(chunk: Buffer): string;
+
+/**
+ * Agent environment policies (roadmap §8, Environment Isolation).
+ *
+ * Four explicit policies, so operators decide exactly what an agent can see:
+ *   - `inherit`   (default, backwards compatible): the full parent environment
+ *   - `allowlist`: only the allow-listed variables (+ PATH/HOME)
+ *   - `denylist`: the parent environment minus the deny-listed variables
+ *   - `explicit`: nothing from the parent; only PATH/HOME and `env`
+ *
+ * The v1 boolean `inherit_env: false` is still honored and maps to `explicit`.
+ */
+
+type EnvPolicy = "inherit" | "allowlist" | "denylist" | "explicit";
+declare function resolveEnvPolicy(config: Partial<AgentConfig>): EnvPolicy;
+declare function buildChildEnv(config: AgentConfig): NodeJS.ProcessEnv;
+
+interface CwdValidation {
+    /** Normalized absolute path. */
+    cwd: string;
+    /** True when the directory sits outside the project root (project boundary). */
+    outsideProject: boolean;
+}
+declare function validateWorkingDirectory(cwd: string | undefined, options?: {
+    projectRoot?: string;
+    allowExternal?: boolean;
+}): CwdValidation | undefined;
+
+interface IAgentAdapter {
+    /** Integration type this adapter serves, e.g. "native" or "process". */
+    readonly integration: string;
+    create(config: AgentConfig): IAgent;
+}
+declare class AgentAdapterRegistry {
+    private readonly adapters;
+    register(adapter: IAgentAdapter): void;
+    get(integration: string): IAgentAdapter | undefined;
+    list(): IAgentAdapter[];
+    create(config: AgentConfig): IAgent;
+}
+/** Process-level adapter — the built-in CLI integration. */
+declare class ProcessAgentAdapter implements IAgentAdapter {
+    private readonly factory;
+    readonly integration = "process";
+    constructor(factory: (config: AgentConfig) => IAgent);
+    create(config: AgentConfig): IAgent;
+}
 
 /** Agent registry (§10): the set of agents connected to OmniNode. */
 
@@ -1695,10 +1955,109 @@ declare class AgentRegistry {
  * "cli" agent configs are mapped to the process integration by the loader.
  */
 
-declare function createAgent(config: AgentConfig): IAgent;
+declare function createAgent(config: AgentConfig, adapters?: AgentAdapterRegistry): 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 {
@@ -2150,6 +2509,6 @@ declare class ProjectStores {
     constructor(directory?: string);
 }
 
-declare const OMNINODE_VERSION = "2.0.0-alpha.2";
+declare const OMNINODE_VERSION = "2.0.0-alpha.4";
 
-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 };
+export { AgentAdapterRegistry, 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 CwdValidation, DEFAULT_MAX_OUTPUT_BYTES, type DecodeResult, type DiscoveryResult, type EnvPolicy, 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 IAgentAdapter, 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, ProcessAgentAdapter, 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, describeExit, encodeMessage, envelope, expandEnvRefs, extractReportFromText, findConfigFile, isOmniNodeError, isSupportedProtocol, keywords, killTree, loadConfig, logger, newMessageId, parseHello, parsePlanJson, pipelineConfigSchema, pipelineStepConfigSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, registryKey, requestJson, requireCompletion, resolveApiKey, resolveEnvPolicy, roleConfigSchema, sanitizeChunk, similar, validateEnvelope, validateWorkingDirectory };