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

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.2";
+var OMNINODE_VERSION = "2.0.0-alpha.4";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -44,11 +44,6 @@ var PipelineError = class extends OmniNodeError {
     super(code, message, options);
   }
 };
-var ProtocolError = class extends OmniNodeError {
-  constructor(message, options = {}) {
-    super("PROTOCOL_VIOLATION", message, options);
-  }
-};
 var PlannerError = class extends OmniNodeError {
   constructor(code, message, options = {}) {
     super(code, message, options);
@@ -88,6 +83,11 @@ var agentConfigSchema = z.object({
   input_mode: z.enum(["stdin", "arg", "protocol"]).default("stdin"),
   timeout_ms: z.number().int().positive().optional(),
   inherit_env: z.boolean().optional(),
+  env_policy: z.enum(["inherit", "allowlist", "denylist", "explicit"]).optional(),
+  env_allowlist: z.array(z.string()).optional(),
+  env_denylist: z.array(z.string()).optional(),
+  max_output_bytes: z.number().int().positive().optional(),
+  allow_external_cwd: z.boolean().optional(),
   metadata: z.record(z.unknown()).optional()
 }).strict();
 var roleConfigSchema = z.object({
@@ -262,6 +262,11 @@ function toAgentConfig(raw) {
     inputMode: raw.input_mode,
     timeoutMs: raw.timeout_ms,
     inheritEnv: raw.inherit_env,
+    envPolicy: raw.env_policy,
+    envAllowlist: raw.env_allowlist,
+    envDenylist: raw.env_denylist,
+    maxOutputBytes: raw.max_output_bytes,
+    allowExternalCwd: raw.allow_external_cwd,
     metadata: raw.metadata
   };
 }
@@ -897,19 +902,416 @@ function registerModelsCommand(program) {
 
 // src/agents/process/index.ts
 import { spawn } from "child_process";
-var DEFAULT_TIMEOUT_MS2 = 6e5;
-var KILL_GRACE_MS = 5e3;
+
+// src/agent-protocol/version.ts
+var PROTOCOL_V2 = "omninode-agent-protocol/2";
+var SUPPORTED_PROTOCOL_VERSIONS = [
+  "omninode-agent-protocol/1",
+  PROTOCOL_V2
+];
+var MAX_MESSAGE_BYTES = 1048576;
+function isSupportedProtocol(protocol) {
+  return SUPPORTED_PROTOCOL_VERSIONS.includes(protocol);
+}
+
+// src/agent-protocol/types.ts
+function newMessageId(prefix = "msg") {
+  const random = Math.random().toString(36).slice(2, 10);
+  return `${prefix}-${Date.now().toString(36)}-${random}`;
+}
+function envelope(type, payload, ids = {}) {
+  return {
+    protocol: PROTOCOL_V2,
+    messageId: newMessageId(),
+    ...ids.requestId !== void 0 ? { requestId: ids.requestId } : {},
+    ...ids.taskId !== void 0 ? { taskId: ids.taskId } : {},
+    ...ids.agentId !== void 0 ? { agentId: ids.agentId } : {},
+    ...ids.pipelineId !== void 0 ? { pipelineId: ids.pipelineId } : {},
+    ...ids.executionId !== void 0 ? { executionId: ids.executionId } : {},
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    type,
+    payload,
+    ...ids.metadata !== void 0 ? { metadata: ids.metadata } : {}
+  };
+}
+
+// src/agent-protocol/codec.ts
+var KNOWN_TYPES = /* @__PURE__ */ new Set([
+  // node → agent
+  "TASK",
+  "HELLO_ACK",
+  "CONTEXT",
+  "INSTRUCTION",
+  "RESPONSE",
+  "CANCEL",
+  // agent → node
+  "HELLO",
+  "TASK_REQUEST",
+  "TASK_ACCEPTED",
+  "TASK_STARTED",
+  "STATUS",
+  "QUESTION",
+  "REPORT",
+  "ARTIFACT",
+  "COMPLETION",
+  "ERROR",
+  "CANCELLED"
+]);
+var PAYLOAD_REQUIRED_TYPES = /* @__PURE__ */ new Set(["TASK", "REPORT", "COMPLETION", "ERROR", "QUESTION", "ARTIFACT", "HELLO"]);
+function validateEnvelope(value, line) {
+  const sample = line?.slice(0, 200);
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, error: { code: "NOT_AN_OBJECT", message: "message must be a JSON object", ...sample ? { sample } : {} } };
+  }
+  const raw = value;
+  const protocol = raw.protocol;
+  if (protocol === void 0) {
+    const type = raw.type;
+    if (typeof type !== "string" || !KNOWN_TYPES.has(type)) {
+      return { ok: false, error: { code: "UNKNOWN_TYPE", message: `unknown message type ${String(type)}`, ...sample ? { sample } : {} } };
+    }
+    return {
+      ok: true,
+      legacy: true,
+      envelope: {
+        protocol: "omninode-agent-protocol/1",
+        messageId: typeof raw.messageId === "string" ? raw.messageId : "legacy",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        type,
+        payload: raw.payload
+      }
+    };
+  }
+  if (typeof protocol !== "string" || !isSupportedProtocol(protocol)) {
+    return {
+      ok: false,
+      error: { code: "UNSUPPORTED_VERSION", message: `unsupported protocol "${String(protocol)}"`, ...sample ? { sample } : {} }
+    };
+  }
+  if (raw.type === void 0) {
+    return { ok: false, error: { code: "MISSING_FIELD", message: "message is missing 'type'", ...sample ? { sample } : {} } };
+  }
+  if (typeof raw.type !== "string" || !KNOWN_TYPES.has(raw.type)) {
+    return { ok: false, error: { code: "UNKNOWN_TYPE", message: `unknown message type ${String(raw.type)}`, ...sample ? { sample } : {} } };
+  }
+  if (raw.timestamp !== void 0 && typeof raw.timestamp !== "string") {
+    return { ok: false, error: { code: "MISSING_FIELD", message: "'timestamp' must be a string", ...sample ? { sample } : {} } };
+  }
+  if (PAYLOAD_REQUIRED_TYPES.has(raw.type) && (raw.payload === void 0 || raw.payload === null)) {
+    return { ok: false, error: { code: "INVALID_PAYLOAD", message: `${raw.type} requires a payload`, ...sample ? { sample } : {} } };
+  }
+  return {
+    ok: true,
+    legacy: protocol !== PROTOCOL_V2,
+    envelope: {
+      protocol,
+      messageId: typeof raw.messageId === "string" ? raw.messageId : "unknown",
+      ...typeof raw.requestId === "string" ? { requestId: raw.requestId } : {},
+      ...typeof raw.taskId === "string" ? { taskId: raw.taskId } : {},
+      ...typeof raw.agentId === "string" ? { agentId: raw.agentId } : {},
+      ...typeof raw.pipelineId === "string" ? { pipelineId: raw.pipelineId } : {},
+      ...typeof raw.executionId === "string" ? { executionId: raw.executionId } : {},
+      timestamp: typeof raw.timestamp === "string" ? raw.timestamp : (/* @__PURE__ */ new Date()).toISOString(),
+      type: raw.type,
+      payload: raw.payload,
+      ...raw.metadata !== null && typeof raw.metadata === "object" ? { metadata: raw.metadata } : {}
+    }
+  };
+}
+function decodeMessage(line, maxBytes = MAX_MESSAGE_BYTES) {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, error: { code: "INVALID_JSON", message: "empty line" } };
+  }
+  if (trimmed.length > maxBytes) {
+    return {
+      ok: false,
+      error: { code: "OVERSIZED", message: `message of ${trimmed.length} bytes exceeds the ${maxBytes} byte limit`, sample: trimmed.slice(0, 200) }
+    };
+  }
+  let value;
+  try {
+    value = JSON.parse(trimmed);
+  } catch (error) {
+    return {
+      ok: false,
+      error: { code: "INVALID_JSON", message: error instanceof Error ? error.message : "invalid JSON", sample: trimmed.slice(0, 200) }
+    };
+  }
+  return validateEnvelope(value, trimmed);
+}
+function encodeMessage(envelope2, maxBytes = MAX_MESSAGE_BYTES) {
+  const line = JSON.stringify(envelope2);
+  if (line.length > maxBytes) {
+    throw new Error(`outbound protocol message of ${line.length} bytes exceeds the ${maxBytes} byte limit`);
+  }
+  return line;
+}
+var ProtocolDecoder = class {
+  buffer = "";
+  maxBytes;
+  constructor(maxBytes = MAX_MESSAGE_BYTES) {
+    this.maxBytes = maxBytes;
+  }
+  push(chunk) {
+    this.buffer += chunk;
+    const results = [];
+    let index = this.buffer.indexOf("\n");
+    while (index >= 0) {
+      const line = this.buffer.slice(0, index);
+      this.buffer = this.buffer.slice(index + 1);
+      if (line.trim().length > 0) results.push(decodeMessage(line, this.maxBytes));
+      index = this.buffer.indexOf("\n");
+    }
+    if (this.buffer.length > this.maxBytes) {
+      results.push({
+        ok: false,
+        error: { code: "OVERSIZED", message: `line exceeded ${this.maxBytes} bytes without a newline`, sample: this.buffer.slice(0, 200) }
+      });
+      this.buffer = "";
+    }
+    return results;
+  }
+  /** Flush any trailing line when the process exits. */
+  flush() {
+    if (this.buffer.trim().length === 0) {
+      this.buffer = "";
+      return [];
+    }
+    const result = decodeMessage(this.buffer, this.maxBytes);
+    this.buffer = "";
+    return [result];
+  }
+};
+
+// src/agent-protocol/handshake.ts
+function parseHello(envelopeValue) {
+  if (envelopeValue.type !== "HELLO") {
+    return { ok: false, reason: `expected HELLO, received ${envelopeValue.type}` };
+  }
+  const payload = envelopeValue.payload;
+  if (payload === null || typeof payload !== "object") {
+    return { ok: false, reason: "HELLO payload must be an object" };
+  }
+  const p = payload;
+  if (typeof p.name !== "string" || p.name.length === 0) {
+    return { ok: false, reason: "HELLO payload is missing 'name'" };
+  }
+  return {
+    ok: true,
+    descriptor: {
+      protocol: envelopeValue.protocol,
+      name: p.name,
+      ...typeof p.version === "string" ? { version: p.version } : {},
+      capabilities: Array.isArray(p.capabilities) ? p.capabilities.filter((c) => typeof c === "string") : [],
+      supports: Array.isArray(p.supports) ? p.supports.filter((s) => typeof s === "string") : []
+    }
+  };
+}
+function buildHelloAck(descriptor) {
+  return envelope("HELLO_ACK", {
+    ok: true,
+    protocol: PROTOCOL_V2,
+    agent: descriptor.name,
+    ...descriptor.version !== void 0 ? { agentVersion: descriptor.version } : {},
+    supportedProtocols: [PROTOCOL_V2]
+  }, { agentId: descriptor.name });
+}
+
+// src/agent-protocol/session.ts
+var ProtocolSession = class {
+  decoder;
+  ids;
+  responder;
+  violations = [];
+  questions = [];
+  artifacts = [];
+  reports = [];
+  descriptor;
+  completionSummary;
+  errorMessage;
+  constructor(ids, options = {}) {
+    this.ids = ids;
+    this.responder = options.responder;
+    this.decoder = new ProtocolDecoder(options.maxBytes);
+  }
+  /** The v2 messages OmniNode sends to open a task (written to the agent's stdin). */
+  taskMessages(objective, role, context, instruction) {
+    const ids = this.ids;
+    const messages = [envelope("TASK", { taskId: ids.taskId, objective }, ids)];
+    if (role !== void 0) messages.push(envelope("CONTEXT", { role }, ids));
+    if (context !== void 0 && context.length > 0) messages.push(envelope("CONTEXT", { body: context }, ids));
+    if (instruction !== void 0 && instruction.length > 0) messages.push(envelope("INSTRUCTION", { text: instruction }, ids));
+    return messages.map((m) => encodeMessage(m));
+  }
+  helloAck(descriptor) {
+    return encodeMessage(buildHelloAck(descriptor));
+  }
+  /** Consumes decoded stdout, answering questions as they arrive. */
+  async handle(decoded) {
+    if (!decoded.ok) {
+      this.violations.push(decoded.error);
+      return;
+    }
+    const message = decoded.envelope;
+    if (message.protocol === PROTOCOL_V2) this.sawV2 = true;
+    if (message.type === "HELLO") {
+      const hello = parseHello(message);
+      if (hello.ok) this.descriptor = hello.descriptor;
+      else this.violations.push({ code: "INVALID_PAYLOAD", message: `bad HELLO: ${hello.reason}` });
+      return;
+    }
+    if (message.type === "QUESTION") {
+      await this.answerQuestion(message);
+      return;
+    }
+    if (message.type === "REPORT") {
+      this.reports.push(message.payload);
+      return;
+    }
+    if (message.type === "ARTIFACT") {
+      this.artifacts.push(message.payload);
+      return;
+    }
+    if (message.type === "COMPLETION") {
+      const payload = message.payload;
+      this.completionSummary = typeof payload?.summary === "string" ? payload.summary : "";
+      return;
+    }
+    if (message.type === "ERROR") {
+      const payload = message.payload;
+      const detail = typeof payload?.message === "string" ? payload.message : "agent reported an error";
+      const code = typeof payload?.code === "string" ? ` [${payload.code}]` : "";
+      this.errorMessage = `Agent error${code}: ${detail}`;
+      return;
+    }
+    if (message.type === "TASK_ACCEPTED" || message.type === "TASK_STARTED" || message.type === "STATUS") {
+      return;
+    }
+    this.violations.push({
+      code: "UNKNOWN_TYPE",
+      message: `unexpected message type ${message.type} from agent`
+    });
+  }
+  async answerQuestion(message) {
+    const payload = message.payload ?? {};
+    const questionId = typeof payload.questionId === "string" ? payload.questionId : message.messageId;
+    const question = typeof payload.question === "string" ? payload.question : "";
+    const expected = typeof payload.expected === "string" ? payload.expected : "text";
+    let answer;
+    if (this.responder) {
+      try {
+        answer = await this.responder({ questionId, question, expected });
+      } catch (error) {
+        this.violations.push({
+          code: "INVALID_PAYLOAD",
+          message: `question responder failed: ${error instanceof Error ? error.message : String(error)}`
+        });
+      }
+    }
+    this.questions.push({ questionId, question, ...answer !== void 0 ? { answer } : {} });
+    this.pendingAnswers.push(
+      encodeMessage(
+        envelope("RESPONSE", { questionId, ...answer !== void 0 ? { body: answer } : {} }, {
+          ...this.ids,
+          requestId: message.requestId ?? this.ids.requestId
+        })
+      )
+    );
+  }
+  pendingAnswers = [];
+  /** True once any inbound message carried the v2 protocol field. */
+  sawV2 = false;
+};
+
+// src/agents/cwd.ts
+import { statSync } from "fs";
+import { isAbsolute, relative, resolve } from "path";
+function validateWorkingDirectory(cwd, options = {}) {
+  if (!cwd) return void 0;
+  const normalized = isAbsolute(cwd) ? resolve(cwd) : resolve(process.cwd(), cwd);
+  let stats;
+  try {
+    stats = statSync(normalized);
+  } catch (error) {
+    throw new AgentError(
+      "AGENT_NOT_FOUND",
+      `Working directory "${normalized}" does not exist or is not accessible.`,
+      { cause: error, details: { cwd: normalized } }
+    );
+  }
+  if (!stats.isDirectory()) {
+    throw new AgentError("AGENT_NOT_FOUND", `Working directory "${normalized}" is not a directory.`, {
+      details: { cwd: normalized }
+    });
+  }
+  try {
+    statSync(resolve(normalized, "."));
+  } catch (error) {
+    throw new AgentError(
+      "AGENT_NOT_FOUND",
+      `Working directory "${normalized}" is not accessible.`,
+      { cause: error }
+    );
+  }
+  const projectRoot = resolve(options.projectRoot ?? process.cwd());
+  const rel = relative(projectRoot, normalized);
+  const outsideProject = rel.startsWith("..") || isAbsolute(rel);
+  if (outsideProject && options.allowExternal !== true) {
+    throw new AgentError(
+      "AGENT_NOT_FOUND",
+      `Working directory "${normalized}" is outside the project root "${projectRoot}". Set allow_external_cwd: true on the agent to permit this.`,
+      { details: { cwd: normalized, projectRoot } }
+    );
+  }
+  return { cwd: normalized, outsideProject };
+}
+
+// src/agents/env.ts
+var BASELINE_KEYS = ["PATH", "HOME"];
+function resolveEnvPolicy(config) {
+  if (config.envPolicy !== void 0) return config.envPolicy;
+  if (config.inheritEnv === false) return "explicit";
+  return "inherit";
+}
 function buildChildEnv(config) {
   const configured = config.env ?? {};
-  if (config.inheritEnv !== false) {
+  const policy = resolveEnvPolicy(config);
+  if (policy === "inherit") {
     return { ...process.env, ...configured };
   }
-  return {
-    PATH: process.env.PATH ?? "",
-    HOME: process.env.HOME ?? "",
-    ...configured
-  };
+  const base = {};
+  for (const key of BASELINE_KEYS) {
+    const value = process.env[key];
+    if (value !== void 0) base[key] = value;
+  }
+  switch (policy) {
+    case "explicit":
+      return { ...base, ...configured };
+    case "allowlist": {
+      const allowed = { ...base };
+      for (const key of config.envAllowlist ?? []) {
+        const value = process.env[key];
+        if (value !== void 0) allowed[key] = value;
+      }
+      return { ...allowed, ...configured };
+    }
+    case "denylist": {
+      const denied = new Set((config.envDenylist ?? []).map((k) => k.toUpperCase()));
+      const filtered = {};
+      for (const [key, value] of Object.entries(process.env)) {
+        if (denied.has(key.toUpperCase())) continue;
+        filtered[key] = value;
+      }
+      return { ...filtered, ...configured };
+    }
+  }
 }
+
+// src/agents/process/index.ts
+var DEFAULT_TIMEOUT_MS2 = 6e5;
+var KILL_GRACE_MS = 5e3;
+var DEFAULT_MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
 function composeTaskText(input) {
   const sections = [`# Objective
 ${input.objective}`];
@@ -930,18 +1332,19 @@ ${input.instruction}`);
   return sections.join("\n\n");
 }
 function buildProtocolMessages(input, agentName) {
-  const meta = {
+  const session = new ProtocolSession({
+    requestId: `req-${input.taskId}`,
     taskId: input.taskId,
-    agent: agentName,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  const messages = [
-    { type: "TASK", payload: { taskId: input.taskId, objective: input.objective } }
-  ];
-  if (input.role) messages.push({ type: "ROLE", payload: input.role });
-  if (input.context) messages.push({ type: "CONTEXT", payload: { body: input.context } });
-  if (input.instruction) messages.push({ type: "INSTRUCTION", payload: { text: input.instruction } });
-  return messages.map((message) => JSON.stringify({ meta, message }));
+    agentId: agentName,
+    ...input.pipelineId !== void 0 ? { pipelineId: input.pipelineId } : {},
+    ...input.executionId !== void 0 ? { executionId: input.executionId } : {}
+  });
+  return session.taskMessages(
+    input.objective,
+    input.role,
+    input.context,
+    input.instruction
+  );
 }
 var ProcessAgent = class {
   config;
@@ -970,40 +1373,73 @@ var ProcessAgent = class {
     }
     const mode = this.config.inputMode ?? "stdin";
     const timeoutMs = this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
+      let cwd;
+      try {
+        cwd = validateWorkingDirectory(this.config.cwd, {
+          allowExternal: this.config.allowExternalCwd
+        })?.cwd;
+      } catch (error) {
+        reject(error);
+        return;
+      }
       const child = spawn(
         command,
         [...this.config.args ?? [], ...mode === "arg" ? [composeTaskText(input)] : []],
         {
-          cwd: this.config.cwd,
+          ...cwd !== void 0 ? { cwd } : {},
           env: buildChildEnv(this.config),
-          stdio: ["pipe", "pipe", "pipe"]
+          stdio: ["pipe", "pipe", "pipe"],
+          // Own process group so the whole tree can be terminated together
+          // (roadmap §8: no orphaned children).
+          ...process.platform === "win32" ? {} : { detached: true }
         }
       );
       this.running.set(input.taskId, child);
+      GLOBAL_RUNNING.add(child);
+      installSignalForwarding();
       let stdout = "";
       let stderr = "";
       let timedOut = false;
+      let outputLimitExceeded = false;
       let settled = false;
+      const maxOutputBytes = this.config.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
       const timer = setTimeout(() => {
         timedOut = true;
-        this.log.warn(`Task ${input.taskId} exceeded ${timeoutMs}ms \u2014 killing process.`);
-        child.kill("SIGTERM");
-        setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS).unref();
+        this.log.warn(`Task ${input.taskId} exceeded ${timeoutMs}ms \u2014 killing process tree.`);
+        killTree(child, "SIGTERM");
+        setTimeout(() => killTree(child, "SIGKILL"), KILL_GRACE_MS).unref();
       }, timeoutMs);
       const settle = (finish) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
         this.running.delete(input.taskId);
+        GLOBAL_RUNNING.delete(child);
         finish();
       };
-      child.stdout?.on("data", (chunk) => {
-        stdout += chunk.toString();
-      });
-      child.stderr?.on("data", (chunk) => {
-        stderr += chunk.toString();
-      });
+      const collect = (into, chunk) => {
+        if (outputLimitExceeded) return;
+        const text = sanitizeChunk(chunk);
+        if (into === "stdout") {
+          if (stdout.length + text.length > maxOutputBytes) {
+            stdout = (stdout + text).slice(0, maxOutputBytes);
+            outputLimitExceeded = true;
+            this.log.warn(`Agent "${this.config.name}" exceeded the ${maxOutputBytes} byte output limit \u2014 killing it.`);
+            killTree(child, "SIGKILL");
+            return;
+          }
+          stdout += text;
+        } else {
+          if (stderr.length + text.length > maxOutputBytes) {
+            stderr = (stderr + text).slice(0, maxOutputBytes);
+            return;
+          }
+          stderr += text;
+        }
+      };
+      child.stdout?.on("data", (chunk) => collect("stdout", chunk));
+      child.stderr?.on("data", (chunk) => collect("stderr", chunk));
       child.stdin?.on("error", () => {
       });
       if (mode !== "arg") {
@@ -1057,7 +1493,7 @@ var ProcessAgent = class {
           const logs = stderr.trim().length > 0 ? stderr.split("\n") : void 0;
           if (mode === "protocol") {
             try {
-              resolve(
+              resolve2(
                 interpretProtocolRun({
                   input,
                   agentName: this.config.name,
@@ -1072,14 +1508,14 @@ var ProcessAgent = class {
             return;
           }
           const trimmed = stdout.trim();
-          resolve({
+          resolve2({
             taskId: input.taskId,
-            status: code === 0 ? "completed" : "failed",
+            status: code === 0 && !outputLimitExceeded ? "completed" : "failed",
             summary: trimmed.length > 0 ? firstLine(trimmed) : void 0,
             rawOutput: trimmed.length > 0 ? trimmed : void 0,
             exitCode: code ?? void 0,
             logs,
-            error: code === 0 ? void 0 : `Process exited with code ${code ?? "unknown"}${signal ? ` (signal: ${signal})` : ""}`
+            ...outputLimitExceeded ? { error: `Agent exceeded the ${maxOutputBytes} byte output limit and was terminated.` } : code === 0 ? {} : { error: describeExit(code, signal) }
           });
         });
       });
@@ -1088,67 +1524,117 @@ var ProcessAgent = class {
   /** Ask the agent to stop current work (SIGTERM). */
   async cancel(taskId) {
     const child = this.running.get(taskId);
-    if (child) child.kill("SIGTERM");
+    if (child) killTree(child, "SIGTERM");
   }
   runningTaskIds() {
     return [...this.running.keys()];
   }
 };
-function interpretProtocolRun({ input, agentName, stdout, exitCode, logs }) {
-  const reports = [];
-  let summary;
-  let error;
-  let sawProtocolMessage = false;
-  for (const line of stdout.split("\n")) {
-    const trimmed2 = line.trim();
-    if (trimmed2.length === 0) continue;
-    const message = parseAgentMessage(trimmed2);
-    if (!message) continue;
-    sawProtocolMessage = true;
-    if (message.type === "REPORT") {
-      const report = normalizeReport(message.payload, input.taskId, agentName, reports.length);
-      if (report) reports.push(report);
-    } else if (message.type === "COMPLETION") {
-      const payload = message.payload;
-      if (typeof payload?.summary === "string") summary = payload.summary;
-    } else if (message.type === "ERROR") {
-      const payload = message.payload;
-      const detail = typeof payload?.message === "string" ? payload.message : "unknown error";
-      const code = typeof payload?.code === "string" ? ` [${payload.code}]` : "";
-      error = `Agent error${code}: ${detail}`;
-    }
+function interpretProtocolRun({
+  input,
+  agentName,
+  stdout,
+  exitCode,
+  logs,
+  responder
+}) {
+  const session = new ProtocolSession(
+    {
+      requestId: `req-${input.taskId}`,
+      taskId: input.taskId,
+      agentId: agentName,
+      ...input.pipelineId !== void 0 ? { pipelineId: input.pipelineId } : {},
+      ...input.executionId !== void 0 ? { executionId: input.executionId } : {}
+    },
+    { ...responder !== void 0 ? { responder } : {} }
+  );
+  for (const result of session.decoder.push(stdout)) {
+    session.handle(result);
   }
-  if (!sawProtocolMessage && exitCode === 0) {
-    throw new ProtocolError(
-      `Agent "${agentName}" produced no protocol messages on stdout (input mode "protocol").`,
-      { details: { taskId: input.taskId, stdout: stdout.slice(0, 2e3) } }
-    );
+  for (const result of session.decoder.flush()) {
+    session.handle(result);
   }
+  const reports = session.reports.flatMap((payload) => Array.isArray(payload) ? payload : [payload]).map((payload, index) => normalizeReport(payload, input.taskId, agentName, index)).filter((report) => report !== void 0);
   const trimmed = stdout.trim();
+  const protocolBlock = {
+    protocol: session.descriptor?.protocol ?? PROTOCOL_V2,
+    legacy: !session.sawV2 && session.descriptor === void 0,
+    ...session.descriptor !== void 0 ? { descriptor: session.descriptor } : {},
+    questions: session.questions,
+    violations: session.violations.map((v) => `${v.code}: ${v.message}`)
+  };
+  if (session.errorMessage !== void 0) {
+    return {
+      taskId: input.taskId,
+      status: "failed",
+      error: session.errorMessage,
+      rawOutput: trimmed.length > 0 ? trimmed : void 0,
+      exitCode: exitCode ?? void 0,
+      logs,
+      protocol: protocolBlock,
+      ...reports.length > 0 ? { reports } : {}
+    };
+  }
+  if (session.descriptor === void 0 && session.violations.length > 0 && session.reports.length === 0 && session.completionSummary === void 0) {
+    return {
+      taskId: input.taskId,
+      status: "failed",
+      error: `agent produced no valid protocol messages: ${protocolBlock.violations.join("; ")}`,
+      rawOutput: trimmed.length > 0 ? trimmed : void 0,
+      exitCode: exitCode ?? void 0,
+      logs,
+      protocol: protocolBlock
+    };
+  }
+  const completed = exitCode === 0 && session.completionSummary !== void 0;
   return {
     taskId: input.taskId,
-    status: error !== void 0 || exitCode !== 0 ? "failed" : "completed",
-    summary: summary ?? reports[0]?.summary,
+    status: completed || exitCode === 0 ? completed ? "completed" : "completed" : "failed",
+    summary: session.completionSummary ?? reports[0]?.summary,
     rawOutput: trimmed.length > 0 ? trimmed : void 0,
     exitCode: exitCode ?? void 0,
     logs,
-    reports: reports.length > 0 ? reports : void 0,
-    error: error ?? (exitCode !== 0 ? `Process exited with code ${exitCode ?? "unknown"}` : void 0)
+    protocol: protocolBlock,
+    ...reports.length > 0 ? { reports } : {},
+    ...exitCode !== 0 ? { error: `Process exited with code ${exitCode ?? "unknown"}` } : {}
   };
 }
-function parseAgentMessage(line) {
-  try {
-    const parsed = JSON.parse(line);
-    if (typeof parsed.type === "string") {
-      return { type: parsed.type, payload: parsed.payload };
-    }
-    const inner = parsed.message;
-    if (inner && typeof inner.type === "string") {
-      return { type: inner.type, payload: inner.payload };
+var GLOBAL_RUNNING = /* @__PURE__ */ new Set();
+var signalForwardingInstalled = false;
+function installSignalForwarding() {
+  if (signalForwardingInstalled) return;
+  signalForwardingInstalled = true;
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => {
+      for (const child of GLOBAL_RUNNING) {
+        killTree(child, "SIGTERM");
+      }
+    });
+  }
+}
+function killTree(child, signal) {
+  if (child.pid === void 0) return;
+  if (process.platform !== "win32") {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
     }
+  }
+  try {
+    child.kill(signal);
   } catch {
   }
-  return void 0;
+}
+function describeExit(code, signal) {
+  if (signal !== null) {
+    return signal === "SIGKILL" ? "Process was killed (SIGKILL) \u2014 usually an external kill or OOM." : `Process terminated by signal ${signal}.`;
+  }
+  if (code === null) return "Process terminated without an exit code.";
+  return `Process exited with code ${code}.`;
+}
+function sanitizeChunk(chunk) {
+  return chunk.toString("utf8").replace(/\u0000/g, "");
 }
 function normalizeReport(payload, taskId, agentName, index) {
   if (payload === null || typeof payload !== "object") return void 0;
@@ -1169,6 +1655,40 @@ function firstLine(text, maxLength = 200) {
   return line.length > maxLength ? `${line.slice(0, maxLength)}\u2026` : line;
 }
 
+// src/agents/adapters.ts
+var AgentAdapterRegistry = class {
+  adapters = /* @__PURE__ */ new Map();
+  register(adapter) {
+    this.adapters.set(adapter.integration, adapter);
+  }
+  get(integration) {
+    return this.adapters.get(integration);
+  }
+  list() {
+    return [...this.adapters.values()];
+  }
+  create(config) {
+    const adapter = this.get(config.integration);
+    if (!adapter) {
+      throw new AgentError(
+        "AGENT_NOT_FOUND",
+        `No agent adapter registered for integration "${config.integration}". Registered: ${[...this.adapters.keys()].join(", ") || "(none)"}.`
+      );
+    }
+    return adapter.create(config);
+  }
+};
+var ProcessAgentAdapter = class {
+  constructor(factory) {
+    this.factory = factory;
+  }
+  factory;
+  integration = "process";
+  create(config) {
+    return this.factory(config);
+  }
+};
+
 // src/agents/registry.ts
 var AgentRegistry = class {
   agents = /* @__PURE__ */ new Map();
@@ -1184,14 +1704,15 @@ var AgentRegistry = class {
 };
 
 // src/agents/factory.ts
-function createAgent(config) {
-  if (config.integration === "process") {
-    return new ProcessAgent(config);
-  }
+var defaultAgentAdapters = new AgentAdapterRegistry();
+defaultAgentAdapters.register(new ProcessAgentAdapter((config) => new ProcessAgent(config)));
+function createAgent(config, adapters = defaultAgentAdapters) {
+  const registered = adapters.get(config.integration);
+  if (registered) return registered.create(config);
   if (config.integration === "native") {
     throw new OmniNodeError(
       "NOT_IMPLEMENTED",
-      `Native agent adapters are planned for a later phase. Use input over stdin/stdout (type "cli") for "${config.name}" for now.`
+      `No native adapter is registered for "${config.name}". Register an IAgentAdapter (createAgent(config, adapters)) or use input over stdin/stdout (type "cli").`
     );
   }
   throw new OmniNodeError("NOT_IMPLEMENTED", `Agent integration "${config.integration}" has no adapter yet.`);
@@ -1234,7 +1755,7 @@ function registerAgentCommands(program) {
     "--input-mode <mode>",
     "How the task is delivered: stdin (prompt on stdin), arg (prompt as last argument) or protocol (\xA721 JSON-lines task protocol).",
     "stdin"
-  ).option(
+  ).option("--env-policy <policy>", "Environment policy: inherit, allowlist, denylist or explicit.").option("--allow-env <name>", "Variable to forward under the allowlist policy (repeatable).", collectArgs).option("--deny-env <name>", "Variable to remove under the denylist policy (repeatable).", collectArgs).option("--max-output-bytes <n>", "Per-stream output budget in bytes (default 5 MiB).", (value) => Number(value)).option("--allow-external-cwd", "Allow a working directory outside the project root.").option(
     "--timeout-ms <ms>",
     "Per-task timeout in milliseconds.",
     (value) => Number(value)
@@ -1249,7 +1770,12 @@ async function addAgent(options) {
     ...options.arg !== void 0 && options.arg.length > 0 ? { args: options.arg } : {},
     ...options.cwd !== void 0 ? { cwd: options.cwd } : {},
     input_mode: options.inputMode,
-    ...options.timeoutMs !== void 0 ? { timeout_ms: options.timeoutMs } : {}
+    ...options.timeoutMs !== void 0 ? { timeout_ms: options.timeoutMs } : {},
+    ...options.envPolicy !== void 0 ? { env_policy: options.envPolicy } : {},
+    ...options.allowEnv !== void 0 && options.allowEnv.length > 0 ? { env_allowlist: options.allowEnv } : {},
+    ...options.denyEnv !== void 0 && options.denyEnv.length > 0 ? { env_denylist: options.denyEnv } : {},
+    ...options.maxOutputBytes !== void 0 ? { max_output_bytes: options.maxOutputBytes } : {},
+    ...options.allowExternalCwd !== void 0 ? { allow_external_cwd: options.allowExternalCwd } : {}
   });
   if (!candidate.success) {
     const issues = candidate.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
@@ -1653,7 +2179,7 @@ function classifyThrown(error) {
   return "failed";
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
 // src/audit/index.ts