@hilbras/omninode 0.3.0 → 0.5.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.3.0";
+var OMNINODE_VERSION = "0.4.0";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -29,6 +29,21 @@ var ProviderError = class extends OmniNodeError {
     super(code, message, options);
   }
 };
+var AgentError = class extends OmniNodeError {
+  constructor(code, message, options = {}) {
+    super(code, message, options);
+  }
+};
+var TaskError = 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 +70,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 +183,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 +262,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 +625,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 +714,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}`
@@ -790,26 +815,381 @@ 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/registry.ts
+var AgentRegistry = class {
+  agents = /* @__PURE__ */ new Map();
+  register(agent) {
+    this.agents.set(agent.info.name, agent);
+  }
+  get(name) {
+    return this.agents.get(name);
+  }
+  list() {
+    return [...this.agents.values()].sort((a, b) => a.info.name.localeCompare(b.info.name));
+  }
+};
+
+// 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.`);
+}
+function buildAgentRegistry(config, log = logger) {
+  const registry = new AgentRegistry();
+  for (const agentConfig of config.project.agents) {
+    try {
+      registry.register(createAgent(agentConfig));
+    } catch (error) {
+      log.warn(
+        `Skipping agent "${agentConfig.name}": ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  return registry;
+}
+
 // 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
@@ -831,19 +1211,305 @@ function registerRoleCommands(program) {
   });
 }
 
+// src/tasks/store.ts
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { dirname } from "path";
+var FileTaskStore = class {
+  filePath;
+  constructor(directory = `${process.cwd()}/.omninode`) {
+    this.filePath = `${directory}/tasks.json`;
+  }
+  async save(task) {
+    const tasks = await this.load();
+    const index = tasks.findIndex((t) => t.id === task.id);
+    if (index >= 0) tasks[index] = task;
+    else tasks.push(task);
+    await this.write(tasks);
+  }
+  async get(id) {
+    const tasks = await this.load();
+    return tasks.find((t) => t.id === id);
+  }
+  async list(filter = {}) {
+    const tasks = await this.load();
+    return tasks.filter((task) => filter.status ? task.status === filter.status : true).filter((task) => filter.project ? task.project === filter.project : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  }
+  async load() {
+    try {
+      const raw = await readFile(this.filePath, "utf8");
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+  async write(tasks) {
+    const tmp = `${this.filePath}.tmp`;
+    await mkdir(dirname(this.filePath), { recursive: true });
+    await writeFile(tmp, `${JSON.stringify(tasks, null, 2)}
+`, "utf8");
+    await rename(tmp, this.filePath);
+  }
+};
+
+// src/tasks/engine.ts
+import { randomBytes } from "crypto";
+var ALLOWED_TRANSITIONS = {
+  created: ["queued", "running", "cancelled"],
+  queued: ["running", "cancelled"],
+  running: ["completed", "failed", "cancelled"],
+  waiting: ["running", "cancelled"],
+  completed: [],
+  failed: [],
+  cancelled: []
+};
+var TaskEngine = class {
+  constructor(options) {
+    this.options = options;
+    this.log = (options.log ?? logger).child({ component: "tasks" });
+  }
+  options;
+  log;
+  get store() {
+    return this.options.store;
+  }
+  async create(input) {
+    if (!input.objective || input.objective.trim().length === 0) {
+      throw new TaskError("TASK_INVALID", "Task objective must not be empty.");
+    }
+    if (input.role && !this.options.roles.get(input.role)) {
+      throw new TaskError(
+        "TASK_INVALID",
+        `Role "${input.role}" is not defined. Add it under project.roles in omninode.yaml.`
+      );
+    }
+    if (input.agent && !this.options.agents.get(input.agent)) {
+      throw new TaskError(
+        "TASK_INVALID",
+        `Agent "${input.agent}" is not registered. Add it with \`omninode agent add\`.`
+      );
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const task = {
+      id: generateTaskId(),
+      objective: input.objective.trim(),
+      status: "created",
+      createdAt: now,
+      updatedAt: now,
+      ...input.project !== void 0 ? { project: input.project } : {},
+      ...input.role !== void 0 ? { role: input.role } : {},
+      ...input.agent !== void 0 ? { agent: input.agent } : {},
+      ...input.context !== void 0 ? { context: input.context } : {}
+    };
+    await this.options.store.save(task);
+    this.log.info(`Created task ${task.id}.`);
+    return task;
+  }
+  async queue(id) {
+    const task = await this.mustGet(id);
+    return this.transition(task, "queued");
+  }
+  /** Runs the task through its assigned agent and records the result. */
+  async run(id) {
+    const task = await this.mustGet(id);
+    if (task.status !== "created" && task.status !== "queued") {
+      throw new TaskError("TASK_INVALID", `Task ${id} is "${task.status}" and cannot be run.`);
+    }
+    if (!task.agent) {
+      throw new TaskError("TASK_INVALID", `Task ${id} has no agent assigned. Re-create it with --agent.`);
+    }
+    const agent = this.options.agents.get(task.agent);
+    if (!agent) {
+      throw new TaskError("TASK_INVALID", `Agent "${task.agent}" is not registered anymore.`);
+    }
+    const role = task.role ? this.options.roles.get(task.role) : void 0;
+    const running = await this.transition(task, "running");
+    this.log.info(`Running task ${task.id} on agent "${task.agent}".`);
+    let output;
+    try {
+      output = await agent.run({
+        taskId: running.id,
+        objective: running.objective,
+        ...role ? { role } : {},
+        ...running.context?.background ? { context: running.context.background } : {}
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.log.error(`Task ${task.id} failed: ${message}`);
+      return this.transition(running, "failed", {
+        result: { error: message, finishedAt: (/* @__PURE__ */ new Date()).toISOString() }
+      });
+    }
+    const result = {
+      ...output.summary !== void 0 ? { summary: output.summary } : {},
+      ...output.reports !== void 0 && output.reports.length > 0 ? { reports: output.reports } : {},
+      ...output.error !== void 0 ? { error: output.error } : {},
+      finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const finalStatus = output.status === "completed" ? "completed" : "failed";
+    this.log.info(`Task ${task.id} finished: ${finalStatus}.`);
+    return this.transition(running, finalStatus, { result });
+  }
+  async cancel(id) {
+    const task = await this.mustGet(id);
+    if (!ALLOWED_TRANSITIONS[task.status].includes("cancelled")) {
+      throw new TaskError("TASK_INVALID", `Task ${id} is "${task.status}" and cannot be cancelled.`);
+    }
+    if (task.agent) {
+      const agent = this.options.agents.get(task.agent);
+      await agent?.cancel?.(task.id);
+    }
+    return this.transition(task, "cancelled");
+  }
+  async get(id) {
+    return this.options.store.get(id);
+  }
+  async list(filter) {
+    return this.options.store.list(filter);
+  }
+  async mustGet(id) {
+    const task = await this.options.store.get(id);
+    if (!task) {
+      throw new TaskError("TASK_NOT_FOUND", `Task "${id}" does not exist in this project's task store.`);
+    }
+    return task;
+  }
+  async transition(task, to, extra = {}) {
+    const allowed = ALLOWED_TRANSITIONS[task.status] ?? [];
+    if (!allowed.includes(to)) {
+      throw new TaskError("TASK_INVALID", `Task ${task.id} cannot move from "${task.status}" to "${to}".`);
+    }
+    const updated = {
+      ...task,
+      status: to,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...extra.result !== void 0 ? { result: { ...task.result, ...extra.result } } : {}
+    };
+    await this.options.store.save(updated);
+    return updated;
+  }
+};
+function generateTaskId() {
+  return `task-${Date.now().toString(36)}-${randomBytes(3).toString("hex")}`;
+}
+
+// src/roles/index.ts
+var RoleRegistry = class {
+  roles = /* @__PURE__ */ new Map();
+  register(role) {
+    this.roles.set(role.id, role);
+  }
+  registerAll(roles) {
+    for (const role of roles) this.register(role);
+  }
+  get(id) {
+    return this.roles.get(id);
+  }
+  list() {
+    return [...this.roles.values()].sort((a, b) => a.id.localeCompare(b.id));
+  }
+};
+function buildRoleRegistry(config) {
+  const registry = new RoleRegistry();
+  registry.registerAll(config.project.roles);
+  return registry;
+}
+
+// src/tasks/engine-factory.ts
+function createTaskEngine(config, log = logger, directory) {
+  return new TaskEngine({
+    agents: buildAgentRegistry(config, log),
+    roles: buildRoleRegistry(config),
+    store: new FileTaskStore(directory),
+    log
+  });
+}
+
 // src/cli/commands/tasks.ts
+var collectFiles = (value, previous) => [...previous, value];
 function registerTaskCommands(program) {
-  const task = program.command("task").description("Create, run and inspect tasks (Phase 4+).");
-  task.command("create").description("Create a task (planned for Phase 4 \u2014 Roles & Tasks).").action(() => {
-    throw notImplemented("omninode task create", "Phase 4 (Roles & Tasks)");
+  const task = program.command("task").description("Create, run and inspect tasks (\xA713).");
+  task.command("create <objective>").description("Create a task. Assign a role and/or agent; run it with `omninode task run`.").option("-r, --role <roleId>", "Role id from project.roles (validated at creation).").option("-a, --agent <name>", "Agent name from project.agents (validated at creation).").option("-f, --file <path>", "File or glob relevant to the task (repeatable).", collectFiles).action(async (objective, options) => {
+    const config = loadConfig();
+    const engine = createTaskEngine(config);
+    const created = await engine.create({
+      objective,
+      project: config.project.name,
+      ...options.role !== void 0 ? { role: options.role } : {},
+      ...options.agent !== void 0 ? { agent: options.agent } : {},
+      ...options.file !== void 0 && options.file.length > 0 ? { context: { files: options.file } } : {}
+    });
+    console.log(`Created task ${created.id} (${created.status})`);
+    console.log(`  objective: ${created.objective}`);
+    if (created.role) console.log(`  role:      ${created.role}`);
+    if (created.agent) console.log(`  agent:     ${created.agent}`);
+    if (created.context?.files) console.log(`  files:     ${created.context.files.join(", ")}`);
+    console.log(`Run \`omninode task run ${created.id}\` to execute it.`);
+  });
+  task.command("run <task-id>").description("Run a task through its assigned agent.").action(async (taskId) => {
+    const config = loadConfig();
+    const engine = createTaskEngine(config);
+    console.log(`Running task ${taskId}...`);
+    const finished = await engine.run(taskId);
+    printOutcome(finished);
+    if (finished.status !== "completed") process.exitCode = 1;
+  });
+  task.command("status <task-id>").description("Show task details and current status.").action(async (taskId) => {
+    const config = loadConfig();
+    const engine = createTaskEngine(config);
+    const found = await engine.get(taskId);
+    if (!found) {
+      throw new TaskError(
+        "TASK_NOT_FOUND",
+        `Task "${taskId}" does not exist in this project's task store.`
+      );
+    }
+    printOutcome(found, { verbose: true });
   });
-  task.command("run <objective>").description("Run a task or pipeline (planned for Phase 5 \u2014 Pipeline Engine).").action(() => {
-    throw notImplemented("omninode task run", "Phase 5 (Pipeline Engine)");
+  task.command("list").description("List tasks in the project's task store.").option("-s, --status <status>", "Filter by status (created, queued, running, completed, failed, cancelled).").action(async (options) => {
+    const config = loadConfig();
+    const engine = createTaskEngine(config);
+    const tasks = await engine.list(
+      options.status !== void 0 ? { status: options.status } : {}
+    );
+    if (tasks.length === 0) {
+      console.log("No tasks found. Create one with `omninode task create`.");
+      return;
+    }
+    for (const t of tasks) {
+      console.log(`${t.id}  ${t.status.padEnd(10)} ${truncate(t.objective, 60)}`);
+    }
   });
-  task.command("status <task-id>").description("Show task status (planned for Phase 4 \u2014 Roles & Tasks).").action(() => {
-    throw notImplemented("omninode task status", "Phase 4 (Roles & Tasks)");
+  task.command("cancel <task-id>").description("Cancel a task that has not finished yet.").action(async (taskId) => {
+    const config = loadConfig();
+    const engine = createTaskEngine(config);
+    const cancelled = await engine.cancel(taskId);
+    console.log(`Task ${cancelled.id} is now "${cancelled.status}".`);
   });
 }
+function printOutcome(task, options = {}) {
+  console.log(`  id:      ${task.id}`);
+  console.log(`  status:  ${task.status}`);
+  console.log(`  created: ${task.createdAt}`);
+  if (options.verbose) {
+    console.log(`  project: ${task.project ?? "(none)"}`);
+    if (task.role) console.log(`  role:    ${task.role}`);
+    if (task.agent) console.log(`  agent:   ${task.agent}`);
+    if (task.context?.files) console.log(`  files:   ${task.context.files.join(", ")}`);
+    console.log(`  objective: ${task.objective}`);
+  }
+  const result = task.result;
+  if (!result) return;
+  if (result.summary) console.log(`  summary: ${result.summary}`);
+  if (result.reports && result.reports.length > 0) {
+    console.log(`  reports: ${result.reports.length} structured report(s)`);
+  }
+  if (result.error) console.log(`  error:   ${result.error}`);
+  if (result.finishedAt) console.log(`  ended:   ${result.finishedAt}`);
+}
+function truncate(text, max) {
+  return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
+}
 
 // src/cli/commands/reports.ts
 function registerReportCommands(program) {