@hilbras/omninode 0.2.0 → 0.4.0

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "0.2.0";
+var OMNINODE_VERSION = "0.4.0";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -29,6 +29,16 @@ var ProviderError = class extends OmniNodeError {
     super(code, message, options);
   }
 };
+var AgentError = class extends OmniNodeError {
+  constructor(code, message, options = {}) {
+    super(code, message, options);
+  }
+};
+var ProtocolError = class extends OmniNodeError {
+  constructor(message, options = {}) {
+    super("PROTOCOL_VIOLATION", message, options);
+  }
+};
 function isOmniNodeError(value) {
   return value instanceof OmniNodeError;
 }
@@ -55,6 +65,8 @@ var agentConfigSchema = z.object({
   args: z.array(z.string()).optional(),
   cwd: z.string().optional(),
   env: z.record(z.string()).optional(),
+  input_mode: z.enum(["stdin", "arg", "protocol"]).default("stdin"),
+  timeout_ms: z.number().int().positive().optional(),
   metadata: z.record(z.unknown()).optional()
 }).strict();
 var roleConfigSchema = z.object({
@@ -166,6 +178,8 @@ function toAgentConfig(raw) {
     args: raw.args,
     cwd: raw.cwd,
     env: raw.env,
+    inputMode: raw.input_mode,
+    timeoutMs: raw.timeout_ms,
     metadata: raw.metadata
   };
 }
@@ -243,10 +257,6 @@ function registerProjectCommands(program) {
   project.command("init").description("Alias of `omninode init`.").option("-f, --force", "Overwrite an existing omninode.yaml.").option("-n, --name <name>", "Project name to write into the configuration.", "My Project").action(async (options) => runInit(options));
 }
 
-// src/cli/commands/providers.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { parseDocument } from "yaml";
-
 // src/providers/auth.ts
 function resolveApiKey(config, env = process.env) {
   if (!config.apiKeyEnvVar) return void 0;
@@ -500,6 +510,49 @@ function inferHealth(error) {
   return status !== void 0 && status >= 500 ? "degraded" : "unreachable";
 }
 
+// src/providers/omnihilbras/index.ts
+var OmniHilbrasProvider = class extends OpenAICompatibleProvider {
+  /**
+   * Run the full connect flow. Throws on authentication or transport failure
+   * (use healthCheck() for a non-throwing probe).
+   */
+  async connect(registry) {
+    const apiKey = resolveApiKey(this.config);
+    const discovered = await this.listModels();
+    const seen = /* @__PURE__ */ new Set();
+    const models = [];
+    const duplicates = [];
+    for (const model of discovered) {
+      if (seen.has(model.id)) {
+        duplicates.push(model.id);
+        continue;
+      }
+      seen.add(model.id);
+      models.push({
+        ...model,
+        provider: this.config.name,
+        status: "available",
+        metadata: { ...model.metadata, gateway: "omnihilbras" }
+      });
+    }
+    if (registry) {
+      for (const model of models) registry.register(model);
+    }
+    const message = `Authenticated${apiKey ? " with API key" : " (no API key configured)"}; validated ${models.length} unique model(s)` + (duplicates.length > 0 ? `, skipped ${duplicates.length} duplicate(s)` : "") + ".";
+    const status = {
+      name: this.config.name,
+      type: this.config.type,
+      baseUrl: this.config.baseUrl,
+      health: "healthy",
+      connected: true,
+      modelCount: models.length,
+      lastCheckedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      message
+    };
+    return { status, models, duplicates, registered: registry ? models.length : 0 };
+  }
+};
+
 // src/providers/factory.ts
 var OPENAI_COMPATIBLE_TYPES = [
   "openai-compatible",
@@ -508,25 +561,95 @@ var OPENAI_COMPATIBLE_TYPES = [
   "custom"
 ];
 function createProvider(config) {
+  if (config.type === "omnihilbras") {
+    return new OmniHilbrasProvider(config);
+  }
   if (OPENAI_COMPATIBLE_TYPES.includes(config.type)) {
     return new OpenAICompatibleProvider(config);
   }
-  if (config.type === "omnihilbras") {
-    throw new OmniNodeError(
-      "NOT_IMPLEMENTED",
-      `Provider type "omnihilbras" is planned for Phase 2 (OmniHilbras Integration). If your OmniHilbras endpoint is OpenAI-compatible, use type "openai-compatible" for now.`
-    );
-  }
   throw new OmniNodeError("NOT_IMPLEMENTED", `Provider type "${config.type}" has no adapter yet.`);
 }
 
+// src/registry/index.ts
+function registryKey(provider, id) {
+  return `${provider}:${id}`;
+}
+var ModelRegistry = class {
+  models = /* @__PURE__ */ new Map();
+  register(model) {
+    this.models.set(registryKey(model.provider, model.id), model);
+  }
+  get(provider, id) {
+    return this.models.get(registryKey(provider, id));
+  }
+  list(filter = {}) {
+    return [...this.models.values()].filter((model) => filter.provider ? model.provider === filter.provider : true).filter(
+      (model) => filter.capability ? model.capabilities?.[filter.capability] === true : true
+    ).sort((a, b) => a.provider.localeCompare(b.provider) || a.id.localeCompare(b.id));
+  }
+  /** Availability validation (§27 Phase 1): present in the registry and not retired. */
+  isAvailable(provider, id) {
+    const model = this.get(provider, id);
+    return model !== void 0 && (model.status ?? "available") === "available";
+  }
+  /** Discover models from one provider and register them. */
+  async discoverFrom(provider) {
+    const discovered = await provider.listModels();
+    for (const model of discovered) this.register(model);
+    return discovered;
+  }
+  /** Discover from many providers; a failing provider does not abort the rest. */
+  async discoverAll(providers) {
+    return Promise.all(
+      providers.map(async (provider) => {
+        try {
+          return {
+            provider: provider.config.name,
+            models: await this.discoverFrom(provider)
+          };
+        } catch (error) {
+          return {
+            provider: provider.config.name,
+            models: [],
+            error: error instanceof Error ? error : new Error(String(error))
+          };
+        }
+      })
+    );
+  }
+};
+
 // src/cli/commands/shared.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { parseDocument } from "yaml";
 function notImplemented(command, when) {
   return new OmniNodeError(
     "NOT_IMPLEMENTED",
     `${command} is planned for ${when}. Edit omninode.yaml directly for now.`
   );
 }
+function appendToConfigList(listKey, item) {
+  const configPath = findConfigFile();
+  if (!configPath) {
+    throw new OmniNodeError("CONFIG_NOT_FOUND", "No omninode.yaml found. Run `omninode init` first.");
+  }
+  const doc = parseDocument(readFileSync2(configPath, "utf8"));
+  if (doc.getIn(["project", listKey]) === void 0) {
+    doc.setIn(["project", listKey], [item]);
+  } else {
+    doc.addIn(["project", listKey], item);
+  }
+  const validated = appConfigSchema.safeParse(doc.toJS());
+  if (!validated.success) {
+    const issues = validated.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+    throw new ConfigError(
+      "CONFIG_INVALID",
+      `Editing ${configPath} would produce an invalid configuration: ${issues}`
+    );
+  }
+  writeFileSync2(configPath, doc.toString(), "utf8");
+  return configPath;
+}
 
 // src/cli/commands/providers.ts
 function registerProviderCommands(program) {
@@ -558,7 +681,10 @@ function registerProviderCommands(program) {
     "--api-key-env-var <envVar>",
     "Environment variable holding the API key. Keys are never written to the config file."
   ).action(async (options) => addProvider(options));
-  provider.command("test <name>").description("Test connectivity, authentication and model discovery for a configured provider.").action(async (name) => testProvider(name));
+  provider.command("test <name>").description("Test connectivity, authentication and model discovery for a configured provider.").option(
+    "--connect",
+    "Run the full provider connect flow (authenticate, fetch, validate, register) where the adapter supports it."
+  ).action(async (name, options) => testProvider(name, options));
   provider.command("remove <name>").description("Remove a provider (planned for Phase 1 follow-up).").action(() => {
     throw notImplemented("omninode provider remove", "a Phase 1 follow-up");
   });
@@ -583,25 +709,11 @@ async function addProvider(options) {
   if (existing.project.providers.some((p) => p.name === newProvider.name)) {
     throw new OmniNodeError(
       "CLI_USAGE",
-      `Provider "${newProvider.name}" already exists in ${configPath}.`
+      `Provider "${newProvider.name}" already exists in ${findConfigFile() ?? "omninode.yaml"}.`
     );
   }
-  const doc = parseDocument(readFileSync2(configPath, "utf8"));
-  if (doc.getIn(["project", "providers"]) === void 0) {
-    doc.setIn(["project", "providers"], [newProvider]);
-  } else {
-    doc.addIn(["project", "providers"], newProvider);
-  }
-  const validated = appConfigSchema.safeParse(doc.toJS());
-  if (!validated.success) {
-    const issues = validated.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
-    throw new ConfigError(
-      "CONFIG_INVALID",
-      `Editing ${configPath} would produce an invalid configuration: ${issues}`
-    );
-  }
-  writeFileSync2(configPath, doc.toString(), "utf8");
-  console.log(`Added provider "${newProvider.name}" (${newProvider.type}) to ${configPath}.`);
+  const writtenPath = appendToConfigList("providers", newProvider);
+  console.log(`Added provider "${newProvider.name}" (${newProvider.type}) to ${writtenPath}.`);
   if (newProvider.api_key_env_var) {
     console.log(
       `Set $${newProvider.api_key_env_var} in your environment, then run: omninode provider test ${newProvider.name}`
@@ -610,7 +722,7 @@ async function addProvider(options) {
     console.log(`Run \`omninode provider test ${newProvider.name}\` to verify connectivity.`);
   }
 }
-async function testProvider(name) {
+async function testProvider(name, options = {}) {
   const config = loadConfig();
   const providerConfig = config.project.providers.find((p) => p.name === name);
   if (!providerConfig) {
@@ -622,62 +734,28 @@ async function testProvider(name) {
   }
   const provider = createProvider(providerConfig);
   console.log(`Testing provider "${name}" (${providerConfig.type}) at ${provider.config.baseUrl}`);
+  if (options.connect && provider instanceof OmniHilbrasProvider) {
+    const registry = new ModelRegistry();
+    try {
+      const result = await provider.connect(registry);
+      printProviderStatus(result.status);
+      console.log(`  registered: ${result.registered}`);
+    } catch (error) {
+      console.log(`  connect failed: ${error instanceof Error ? error.message : String(error)}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
   const health = await provider.healthCheck();
-  console.log(`  health:    ${health.health}`);
-  console.log(`  connected: ${health.connected}`);
-  console.log(`  models:    ${health.modelCount}`);
-  if (health.message) console.log(`  detail:    ${health.message}`);
+  printProviderStatus(health);
   if (!health.connected) process.exitCode = 1;
 }
-
-// src/registry/index.ts
-function registryKey(provider, id) {
-  return `${provider}:${id}`;
+function printProviderStatus(status) {
+  console.log(`  health:    ${status.health}`);
+  console.log(`  connected: ${status.connected}`);
+  console.log(`  models:    ${status.modelCount}`);
+  if (status.message) console.log(`  detail:    ${status.message}`);
 }
-var ModelRegistry = class {
-  models = /* @__PURE__ */ new Map();
-  register(model) {
-    this.models.set(registryKey(model.provider, model.id), model);
-  }
-  get(provider, id) {
-    return this.models.get(registryKey(provider, id));
-  }
-  list(filter = {}) {
-    return [...this.models.values()].filter((model) => filter.provider ? model.provider === filter.provider : true).filter(
-      (model) => filter.capability ? model.capabilities?.[filter.capability] === true : true
-    ).sort((a, b) => a.provider.localeCompare(b.provider) || a.id.localeCompare(b.id));
-  }
-  /** Availability validation (§27 Phase 1): present in the registry and not retired. */
-  isAvailable(provider, id) {
-    const model = this.get(provider, id);
-    return model !== void 0 && (model.status ?? "available") === "available";
-  }
-  /** Discover models from one provider and register them. */
-  async discoverFrom(provider) {
-    const discovered = await provider.listModels();
-    for (const model of discovered) this.register(model);
-    return discovered;
-  }
-  /** Discover from many providers; a failing provider does not abort the rest. */
-  async discoverAll(providers) {
-    return Promise.all(
-      providers.map(async (provider) => {
-        try {
-          return {
-            provider: provider.config.name,
-            models: await this.discoverFrom(provider)
-          };
-        } catch (error) {
-          return {
-            provider: provider.config.name,
-            models: [],
-            error: error instanceof Error ? error : new Error(String(error))
-          };
-        }
-      })
-    );
-  }
-};
 
 // src/cli/commands/models.ts
 var CAPABILITIES = [
@@ -732,26 +810,354 @@ function registerModelsCommand(program) {
   });
 }
 
+// src/agents/process/index.ts
+import { spawn } from "child_process";
+var DEFAULT_TIMEOUT_MS2 = 6e5;
+var KILL_GRACE_MS = 5e3;
+function composeTaskText(input) {
+  const sections = [`# Objective
+${input.objective}`];
+  if (input.role) {
+    const lines = ["# Role", `${input.role.name} (${input.role.id})`];
+    if (input.role.responsibilities.length > 0) {
+      lines.push("", "Responsibilities:", ...input.role.responsibilities.map((r) => `- ${r}`));
+    }
+    if (input.role.expectedOutputs.length > 0) {
+      lines.push("", "Expected outputs:", ...input.role.expectedOutputs.map((o) => `- ${o}`));
+    }
+    sections.push(lines.join("\n"));
+  }
+  if (input.context) sections.push(`# Context
+${input.context}`);
+  if (input.instruction) sections.push(`# Instruction
+${input.instruction}`);
+  return sections.join("\n\n");
+}
+function buildProtocolMessages(input, agentName) {
+  const meta = {
+    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 }));
+}
+var ProcessAgent = class {
+  config;
+  info;
+  log;
+  running = /* @__PURE__ */ new Map();
+  constructor(config, log = logger) {
+    if (!config.command) {
+      throw new AgentError("AGENT_NOT_FOUND", `Agent "${config.name}" has no command configured.`);
+    }
+    this.config = config;
+    this.log = log.child({ agent: config.name });
+    this.info = {
+      name: config.name,
+      integration: "process",
+      command: config.command,
+      cwd: config.cwd,
+      status: "ready",
+      capabilities: [config.inputMode ?? "stdin"]
+    };
+  }
+  async run(input) {
+    const command = this.config.command;
+    if (!command) {
+      throw new AgentError("AGENT_NOT_FOUND", `Agent "${this.config.name}" has no command configured.`);
+    }
+    const mode = this.config.inputMode ?? "stdin";
+    const timeoutMs = this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+    return new Promise((resolve, reject) => {
+      const child = spawn(
+        command,
+        [...this.config.args ?? [], ...mode === "arg" ? [composeTaskText(input)] : []],
+        {
+          cwd: this.config.cwd,
+          env: { ...process.env, ...this.config.env },
+          stdio: ["pipe", "pipe", "pipe"]
+        }
+      );
+      this.running.set(input.taskId, child);
+      let stdout = "";
+      let stderr = "";
+      let timedOut = false;
+      let settled = false;
+      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();
+      }, timeoutMs);
+      const settle = (finish) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        this.running.delete(input.taskId);
+        finish();
+      };
+      child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+      child.stdin?.on("error", () => {
+      });
+      if (mode !== "arg") {
+        const payload = mode === "protocol" ? buildProtocolMessages(input, this.config.name).join("\n") + "\n" : composeTaskText(input) + "\n";
+        child.stdin?.write(payload);
+        child.stdin?.end();
+      }
+      child.on("error", (error) => {
+        settle(() => {
+          if (error.code === "ENOENT") {
+            reject(
+              new AgentError(
+                "AGENT_NOT_FOUND",
+                `Agent "${this.config.name}": command "${command}" was not found. Is it installed and on PATH?`,
+                { cause: error }
+              )
+            );
+            return;
+          }
+          reject(
+            new AgentError("AGENT_FAILED", `Agent "${this.config.name}" failed to start: ${error.message}.`, {
+              cause: error
+            })
+          );
+        });
+      });
+      child.on("close", (code, signal) => {
+        settle(() => {
+          if (timedOut) {
+            reject(
+              new AgentError(
+                "AGENT_TIMEOUT",
+                `Agent "${this.config.name}" timed out after ${timeoutMs}ms and was killed.`,
+                { details: { taskId: input.taskId, stdout: stdout.slice(0, 4e3), stderr: stderr.slice(0, 2e3) } }
+              )
+            );
+            return;
+          }
+          const logs = stderr.trim().length > 0 ? stderr.split("\n") : void 0;
+          if (mode === "protocol") {
+            try {
+              resolve(
+                interpretProtocolRun({
+                  input,
+                  agentName: this.config.name,
+                  stdout,
+                  exitCode: code,
+                  logs
+                })
+              );
+            } catch (error) {
+              reject(error);
+            }
+            return;
+          }
+          const trimmed = stdout.trim();
+          resolve({
+            taskId: input.taskId,
+            status: code === 0 ? "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})` : ""}`
+          });
+        });
+      });
+    });
+  }
+  /** Ask the agent to stop current work (SIGTERM). */
+  async cancel(taskId) {
+    const child = this.running.get(taskId);
+    if (child) child.kill("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}`;
+    }
+  }
+  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) } }
+    );
+  }
+  const trimmed = stdout.trim();
+  return {
+    taskId: input.taskId,
+    status: error !== void 0 || exitCode !== 0 ? "failed" : "completed",
+    summary: summary ?? 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)
+  };
+}
+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 };
+    }
+  } catch {
+  }
+  return void 0;
+}
+function normalizeReport(payload, taskId, agentName, index) {
+  if (payload === null || typeof payload !== "object") return void 0;
+  const raw = payload;
+  if (typeof raw.summary !== "string") return void 0;
+  return {
+    id: typeof raw.id === "string" ? raw.id : `${taskId}-report-${index}`,
+    taskId: typeof raw.taskId === "string" ? raw.taskId : taskId,
+    agent: typeof raw.agent === "string" ? raw.agent : agentName,
+    summary: raw.summary,
+    findings: Array.isArray(raw.findings) ? raw.findings : [],
+    recommendations: Array.isArray(raw.recommendations) ? raw.recommendations : [],
+    createdAt: typeof raw.createdAt === "string" ? raw.createdAt : (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function firstLine(text, maxLength = 200) {
+  const line = text.split("\n", 1)[0] ?? text;
+  return line.length > maxLength ? `${line.slice(0, maxLength)}\u2026` : line;
+}
+
+// src/agents/factory.ts
+function createAgent(config) {
+  if (config.integration === "process") {
+    return new ProcessAgent(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.`
+    );
+  }
+  throw new OmniNodeError("NOT_IMPLEMENTED", `Agent integration "${config.integration}" has no adapter yet.`);
+}
+
 // src/cli/commands/agents.ts
+var collectArgs = (value, previous) => [...previous, value];
 function registerAgentCommands(program) {
   const agent = program.command("agent").description("Manage CLI agents registered with OmniNode.");
   agent.command("list").description("List configured agents.").action(async () => {
     const config = loadConfig();
     const agents = config.project.agents;
     if (agents.length === 0) {
-      console.log("No agents configured. Add one under `project.agents` in omninode.yaml.");
+      console.log("No agents configured. Add one with `omninode agent add` or edit omninode.yaml.");
       return;
     }
     for (const agent2 of agents) {
       const command = agent2.command ?? "(no command)";
       console.log(
-        `${agent2.name}  integration=${agent2.integration}  command=${command}`
+        `${agent2.name}  integration=${agent2.integration}  command=${command}  input=${agent2.inputMode ?? "stdin"}`
       );
     }
   });
-  agent.command("add").description("Register an agent (planned for Phase 3 \u2014 CLI Agent System).").action(() => {
-    throw notImplemented("omninode agent add", "Phase 3 (CLI Agent System)");
+  agent.command("add").description(
+    "Register a CLI agent in omninode.yaml. Agents run as child processes (stdin/stdout); native adapters come in a later phase."
+  ).requiredOption("--name <name>", "Unique agent name.").requiredOption("--command <command>", "Executable command, e.g. opencode").option("--arg <value>", "Additional command argument (repeatable).", collectArgs, []).option("--cwd <dir>", "Working directory for the agent process.").option(
+    "--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(
+    "--timeout-ms <ms>",
+    "Per-task timeout in milliseconds.",
+    (value) => Number(value)
+  ).action(async (options) => addAgent(options));
+  agent.command("test <name>").description("Verify the OmniNode \u2194 agent connection by sending a trivial task.").action(async (name) => testAgent(name));
+}
+async function addAgent(options) {
+  const candidate = agentConfigSchema.safeParse({
+    name: options.name,
+    type: "cli",
+    command: options.command,
+    ...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 } : {}
   });
+  if (!candidate.success) {
+    const issues = candidate.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+    throw new OmniNodeError("CLI_USAGE", `Invalid agent options: ${issues}`);
+  }
+  const newAgent = candidate.data;
+  const existing = loadConfig();
+  if (existing.project.agents.some((a) => a.name === newAgent.name)) {
+    throw new OmniNodeError(
+      "CLI_USAGE",
+      `Agent "${newAgent.name}" already exists in omninode.yaml. Remove it first or pick another name.`
+    );
+  }
+  const configPath = appendToConfigList("agents", newAgent);
+  console.log(`Added agent "${newAgent.name}" (${newAgent.type}, input=${newAgent.input_mode}) to ${configPath}.`);
+  console.log(`Run \`omninode agent test ${newAgent.name}\` to verify the connection.`);
+}
+async function testAgent(name) {
+  const config = loadConfig();
+  const agentConfig = config.project.agents.find((a) => a.name === name);
+  if (!agentConfig) {
+    const available = config.project.agents.map((a) => a.name).join(", ") || "(none)";
+    throw new AgentError(
+      "AGENT_NOT_FOUND",
+      `Agent "${name}" is not configured. Configured agents: ${available}.`
+    );
+  }
+  const agent = createAgent(agentConfig);
+  console.log(
+    `Testing agent "${name}" (${agent.info.integration}, input=${agentConfig.inputMode ?? "stdin"}) \u2014 sending a trivial task.`
+  );
+  const result = await agent.run({
+    taskId: `test-${Date.now()}`,
+    objective: "Reply with the single word: OK"
+  });
+  console.log(`  status: ${result.status}`);
+  if (result.exitCode !== void 0) console.log(`  exit:   ${result.exitCode}`);
+  if (result.summary) console.log(`  output: ${result.summary}`);
+  if (result.rawOutput && result.rawOutput !== result.summary) {
+    console.log(`  raw:    ${result.rawOutput.slice(0, 200).replace(/\n/g, " ")}`);
+  }
+  if (result.error) console.log(`  error:  ${result.error}`);
+  if (result.status !== "completed") process.exitCode = 1;
 }
 
 // src/cli/commands/roles.ts