@hilbras/omninode 0.3.0 → 0.4.0

package/README.md

@@ -18,7 +18,7 @@ existing intelligence; it does not try to become another model.
 
 ## Status
 
-**v0.3.0 — Phase 2: OmniHilbras Integration** (see [docs/DEVELOPMENT_PLAN.md](docs/DEVELOPMENT_PLAN.md)
+**v0.4.0 — Phase 3: CLI Agent System** (see [docs/DEVELOPMENT_PLAN.md](docs/DEVELOPMENT_PLAN.md)
 for the full plan and roadmap).
 
 What exists today:
@@ -35,6 +35,15 @@ What exists today:
   - Provider factory mapping config to adapters; `omnihilbras` gets a
     dedicated adapter implementing the plan's connect flow —
     Connect → Authenticate → Fetch Models → Validate Models → Register
+- **Agent system** (`src/agents/`):
+  - Process adapter: spawns CLI agents as child processes with lifecycle
+    management — environment, working directory, exit codes, stderr logs,
+    per-task timeouts (SIGTERM → SIGKILL) and cancellation
+  - Three input modes: `stdin` (composed task text on stdin), `arg` (prompt as
+    last argument) and `protocol` (the §21 JSON-lines task protocol —
+    `TASK`/`ROLE`/`CONTEXT`/`INSTRUCTION` envelopes in, `REPORT`/`COMPLETION`/
+    `ERROR` messages out, parsed into structured reports)
+  - Agent factory and registry (`createAgent`, `AgentRegistry`)
 - Typed error hierarchy (`src/errors/`)
 - Leveled logger with pluggable sink (`src/logger/`)
 - Configuration system: `omninode.yaml` with `${ENV_VAR}` expansion and strict
@@ -76,6 +85,14 @@ omninode agent list
 omninode role list
 ```
 
+Register and verify a CLI agent (anything executable works — `opencode`,
+`kimi`, a custom script):
+
+```bash
+omninode agent add --name opencode --command opencode --input-mode arg
+omninode agent test opencode     # sends a trivial task over the real adapter
+```
+
 See [omninode.yaml.example](omninode.yaml.example) for a full configuration.
 
 ### Configuration
@@ -107,8 +124,8 @@ Phases 0–11 are laid out in [docs/DEVELOPMENT_PLAN.md](docs/DEVELOPMENT_PLAN.m
 | --- | --- |
 | v0.1.0 | Foundation |
 | v0.2.0 | Provider System |
-| **v0.3.0** | **OmniHilbras Integration (current)** |
-| v0.4.0 | Agent System |
+| v0.3.0 | OmniHilbras Integration (optional, like every provider) |
+| **v0.4.0** | **CLI Agent System (current)** |
 | v0.5.0 | Roles & Tasks |
 | v0.6.0 | Pipeline Engine |
 | v0.7.0 | Multi-AI Reports |

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "0.3.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;
@@ -610,12 +620,36 @@ var ModelRegistry = class {
 };
 
 // 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) {
@@ -675,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}.`
-    );
-  }
-  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}`
+      `Provider "${newProvider.name}" already exists in ${findConfigFile() ?? "omninode.yaml"}.`
     );
   }
-  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}`
@@ -790,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