@hilbras/omninode 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,12 @@
 # OmniNode
 
+[![CI](https://github.com/Hilbras/OmniNode/actions/workflows/ci.yml/badge.svg)](https://github.com/Hilbras/OmniNode/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@hilbras/omninode)](https://www.npmjs.com/package/@hilbras/omninode)
+[![npm downloads](https://img.shields.io/npm/dm/@hilbras/omninode)](https://www.npmjs.com/package/@hilbras/omninode)
+[![Node.js support](https://img.shields.io/node/v/@hilbras/omninode)](https://www.npmjs.com/package/@hilbras/omninode)
+[![License: MIT](https://img.shields.io/github/license/Hilbras/OmniNode)](LICENSE)
+[![Roadmap phase](https://img.shields.io/badge/phase-0_%2F_11-Foundation-8A2BE2)](docs/DEVELOPMENT_PLAN.md)
+
 **OmniNode** is a provider-agnostic multi-AI orchestration platform. It coordinates
 CLI-based AI agents, AI providers, persistent memory, roles, reports and planning
 into a unified execution system — so multiple AI systems can collaborate on complex
@@ -11,23 +18,30 @@ existing intelligence; it does not try to become another model.
 
 ## Status
 
-**v0.1.0 — Phase 0: Foundation** (see [docs/DEVELOPMENT_PLAN.md](docs/DEVELOPMENT_PLAN.md)
+**v0.2.0 — Phase 1: Provider Infrastructure** (see [docs/DEVELOPMENT_PLAN.md](docs/DEVELOPMENT_PLAN.md)
 for the full plan and roadmap).
 
 What exists today:
 
 - Core type contracts: provider, model, agent, role, task, report, pipeline,
   protocol, memory (`src/types/`)
+- **Provider system** (`src/providers/`, `src/registry/`):
+  - OpenAI-compatible adapter — works with OpenAI, OpenRouter, local runtimes
+    (Ollama, LM Studio, vLLM) and custom gateways exposing `/models` and `/chat/completions`
+  - Model discovery with normalization into the model registry (`provider:model` keys)
+  - Health checks: connectivity, authentication and server-error classification
+  - Authentication from environment variables only — keys never touch config files
+  - Chat completions (`IChatProvider`) — the foundation for the planner phases
+  - Provider factory mapping config to adapters (OmniHilbras gets a dedicated
+    adapter in Phase 2)
 - Typed error hierarchy (`src/errors/`)
 - Leveled logger with pluggable sink (`src/logger/`)
 - Configuration system: `omninode.yaml` with `${ENV_VAR}` expansion and strict
   validation (`src/config/`)
-- CLI with `init`, `provider list`, `agent list`, `role list`, and honest
-  stubs for the phase-dependent commands (`src/cli/`)
+- CLI: `init`, `provider add/list/test`, `models`, `agent list`, `role list`,
+  and honest stubs for the phase-dependent commands (`src/cli/`)
 - Test infrastructure (Vitest) and CI (GitHub Actions)
 
-Nothing here depends on any provider or agent — that is the point of Phase 0.
-
 ## Requirements
 
 - Node.js >= 20
@@ -46,8 +60,17 @@ npm run omninode -- --help
 Start a project:
 
 ```bash
-omninode init            # writes omninode.yaml in the current directory
-omninode provider list   # validates and lists configured providers
+omninode init                 # writes omninode.yaml in the current directory
+
+# Register a provider and verify it end to end
+omninode provider add --name my-gateway --type openai-compatible \
+  --base-url https://example.com/v1 --api-key-env-var MY_API_KEY
+omninode provider test my-gateway
+
+# Discover models into the registry
+omninode models
+omninode models my-gateway --capability chat
+
 omninode agent list
 omninode role list
 ```
@@ -81,8 +104,8 @@ Phases 0–11 are laid out in [docs/DEVELOPMENT_PLAN.md](docs/DEVELOPMENT_PLAN.m
 
 | Version | Milestone |
 | --- | --- |
-| v0.1.0 | Foundation (this release) |
-| v0.2.0 | Provider System |
+| v0.1.0 | Foundation |
+| **v0.2.0** | **Provider System (current)** |
 | v0.3.0 | OmniHilbras Integration (optional, like every provider) |
 | v0.4.0 | Agent System |
 | v0.5.0 | Roles & Tasks |

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "0.1.0";
+var OMNINODE_VERSION = "0.2.0";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -24,6 +24,11 @@ var ConfigError = class extends OmniNodeError {
     super(code, message, options);
   }
 };
+var ProviderError = class extends OmniNodeError {
+  constructor(code, message, options = {}) {
+    super(code, message, options);
+  }
+};
 function isOmniNodeError(value) {
   return value instanceof OmniNodeError;
 }
@@ -238,6 +243,291 @@ 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;
+  const value = env[config.apiKeyEnvVar];
+  if (!value) {
+    throw new ProviderError(
+      "PROVIDER_AUTH_FAILED",
+      `Environment variable "${config.apiKeyEnvVar}" (referenced by provider "${config.name}") is not set.`
+    );
+  }
+  return value;
+}
+function authHeaders(config, env = process.env) {
+  const key = resolveApiKey(config, env);
+  const base = { ...config.headers ?? {} };
+  return key ? { ...base, authorization: `Bearer ${key}` } : base;
+}
+
+// src/providers/http.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+async function requestJson(url, options = {}) {
+  const { method = "GET", headers = {}, body, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+  let response;
+  try {
+    response = await fetch(url, {
+      method,
+      headers: {
+        accept: "application/json",
+        ...body !== void 0 ? { "content-type": "application/json" } : {},
+        ...headers
+      },
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {},
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  } catch (error) {
+    const reason = error instanceof Error && error.name === "TimeoutError" ? `timed out after ${timeoutMs}ms` : error instanceof Error ? error.message : String(error);
+    throw new ProviderError("PROVIDER_UNAVAILABLE", `Request to ${url} failed: ${reason}.`, {
+      cause: error
+    });
+  }
+  let parsed;
+  try {
+    parsed = await response.json();
+  } catch (error) {
+    throw new ProviderError("PROVIDER_UNAVAILABLE", `Response from ${url} was not valid JSON.`, {
+      cause: error,
+      details: { status: response.status }
+    });
+  }
+  return { status: response.status, body: parsed };
+}
+
+// src/logger/index.ts
+var LEVEL_ORDER = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+var ConsoleLogSink = class {
+  constructor(stream = process.stderr) {
+    this.stream = stream;
+  }
+  stream;
+  write(_level, line) {
+    this.stream.write(line + "\n");
+  }
+};
+var Logger = class _Logger {
+  level;
+  sink;
+  context;
+  constructor(options = {}) {
+    this.level = options.level ?? "info";
+    this.sink = options.sink ?? new ConsoleLogSink();
+    this.context = options.context ?? {};
+  }
+  child(context) {
+    return new _Logger({
+      level: this.level,
+      sink: this.sink,
+      context: { ...this.context, ...context }
+    });
+  }
+  debug(message, data) {
+    this.log("debug", message, data);
+  }
+  info(message, data) {
+    this.log("info", message, data);
+  }
+  warn(message, data) {
+    this.log("warn", message, data);
+  }
+  error(message, data) {
+    this.log("error", message, data);
+  }
+  log(level, message, data) {
+    if (LEVEL_ORDER[level] < LEVEL_ORDER[this.level]) return;
+    const parts = [(/* @__PURE__ */ new Date()).toISOString(), level.toUpperCase(), message];
+    const merged = { ...this.context, ...data };
+    if (Object.keys(merged).length > 0) {
+      parts.push(JSON.stringify(merged));
+    }
+    this.sink.write(level, parts.join(" "));
+  }
+};
+var logger = new Logger();
+
+// src/providers/openai-compatible/index.ts
+var OpenAICompatibleProvider = class {
+  config;
+  log;
+  constructor(config, log = logger) {
+    this.config = { ...config, baseUrl: normalizeBaseUrl(config.baseUrl) };
+    this.log = log.child({ provider: config.name });
+  }
+  async listModels() {
+    const { status, body } = await requestJson(`${this.config.baseUrl}/models`, {
+      headers: authHeaders(this.config)
+    });
+    if (status === 401 || status === 403) {
+      throw authFailed(this.config, status);
+    }
+    if (status !== 200) {
+      throw unavailable(this.config, `Model discovery returned HTTP ${status}.`, status);
+    }
+    const entries = extractModelEntries(body, this.config);
+    const models = [];
+    let skipped = 0;
+    for (const entry2 of entries) {
+      if (typeof entry2.id !== "string" || entry2.id.length === 0) {
+        skipped += 1;
+        continue;
+      }
+      models.push({
+        provider: this.config.name,
+        id: entry2.id,
+        displayName: entry2.id,
+        status: "available",
+        metadata: {
+          ...typeof entry2.owned_by === "string" ? { ownedBy: entry2.owned_by } : {},
+          ...typeof entry2.created === "number" ? { createdAt: entry2.created } : {}
+        }
+      });
+    }
+    if (skipped > 0) {
+      this.log.warn(`Skipped ${skipped} model entr(y/ies) without a valid id.`);
+    }
+    return models;
+  }
+  async healthCheck() {
+    const lastCheckedAt = (/* @__PURE__ */ new Date()).toISOString();
+    try {
+      const started = Date.now();
+      const models = await this.listModels();
+      return {
+        name: this.config.name,
+        type: this.config.type,
+        baseUrl: this.config.baseUrl,
+        health: "healthy",
+        connected: true,
+        modelCount: models.length,
+        lastCheckedAt,
+        message: `Discovered ${models.length} model(s) in ${Date.now() - started}ms.`
+      };
+    } catch (error) {
+      return {
+        name: this.config.name,
+        type: this.config.type,
+        baseUrl: this.config.baseUrl,
+        health: inferHealth(error),
+        connected: false,
+        modelCount: 0,
+        lastCheckedAt,
+        message: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  async chat(request) {
+    const { status, body } = await requestJson(`${this.config.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: authHeaders(this.config),
+      body: {
+        model: request.model,
+        messages: request.messages,
+        ...request.temperature !== void 0 ? { temperature: request.temperature } : {},
+        ...request.maxTokens !== void 0 ? { max_tokens: request.maxTokens } : {},
+        ...request.stop !== void 0 ? { stop: request.stop } : {}
+      }
+    });
+    if (status === 401 || status === 403) throw authFailed(this.config, status);
+    if (status === 404) {
+      throw new ProviderError(
+        "MODEL_NOT_FOUND",
+        `Model "${request.model}" or the chat endpoint was not found on provider "${this.config.name}" (HTTP 404).`,
+        { details: { status } }
+      );
+    }
+    if (status !== 200) {
+      throw unavailable(this.config, `Chat completion returned HTTP ${status}.`, status);
+    }
+    const payload = body;
+    const choices = Array.isArray(payload.choices) ? payload.choices : [];
+    const first = choices[0];
+    if (!first || typeof first.message?.content !== "string") {
+      throw unavailable(this.config, "Chat completion response had no message content.", status);
+    }
+    const usage = payload.usage ?? {};
+    return {
+      model: typeof payload.model === "string" ? payload.model : request.model,
+      content: first.message.content,
+      finishReason: typeof first.finish_reason === "string" ? first.finish_reason : void 0,
+      usage: {
+        promptTokens: typeof usage.prompt_tokens === "number" ? usage.prompt_tokens : void 0,
+        completionTokens: typeof usage.completion_tokens === "number" ? usage.completion_tokens : void 0,
+        totalTokens: typeof usage.total_tokens === "number" ? usage.total_tokens : void 0
+      },
+      raw: body
+    };
+  }
+};
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/+$/, "");
+}
+function extractModelEntries(body, config) {
+  if (Array.isArray(body)) return body;
+  if (body !== null && typeof body === "object" && Array.isArray(body.data)) {
+    return body.data;
+  }
+  throw new ProviderError(
+    "PROVIDER_UNAVAILABLE",
+    `Provider "${config.name}" returned an unrecognized model list shape.`,
+    { details: { endpoint: "models" } }
+  );
+}
+function authFailed(config, status) {
+  const envHint = config.apiKeyEnvVar ? ` Check that $${config.apiKeyEnvVar} is set and valid.` : " The provider requires authentication; configure api_key_env_var for it.";
+  return new ProviderError(
+    "PROVIDER_AUTH_FAILED",
+    `Authentication with provider "${config.name}" failed (HTTP ${status}).${envHint}`,
+    { details: { status } }
+  );
+}
+function unavailable(config, message, status) {
+  return new ProviderError("PROVIDER_UNAVAILABLE", `Provider "${config.name}": ${message}`, {
+    details: { status }
+  });
+}
+function inferHealth(error) {
+  const status = error instanceof ProviderError && typeof error.details?.status === "number" ? error.details.status : void 0;
+  return status !== void 0 && status >= 500 ? "degraded" : "unreachable";
+}
+
+// src/providers/factory.ts
+var OPENAI_COMPATIBLE_TYPES = [
+  "openai-compatible",
+  "openrouter",
+  "local",
+  "custom"
+];
+function createProvider(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/cli/commands/shared.ts
+function notImplemented(command, when) {
+  return new OmniNodeError(
+    "NOT_IMPLEMENTED",
+    `${command} is planned for ${when}. Edit omninode.yaml directly for now.`
+  );
+}
+
 // src/cli/commands/providers.ts
 function registerProviderCommands(program) {
   const provider = program.command("provider").description("Manage AI providers configured in omninode.yaml.");
@@ -246,7 +536,7 @@ function registerProviderCommands(program) {
     const providers = config.project.providers;
     if (providers.length === 0) {
       console.log(
-        "No providers configured. Add one under `project.providers` in omninode.yaml."
+        "No providers configured. Add one with `omninode provider add` or edit omninode.yaml."
       );
       return;
     }
@@ -258,15 +548,188 @@ function registerProviderCommands(program) {
       );
     }
   });
-  provider.command("add").description("Add a provider (planned for Phase 1 \u2014 Provider Infrastructure).").action(() => {
-    throw notImplemented("omninode provider add", "Phase 1 (Provider Infrastructure)");
+  provider.command("add").description(
+    "Add a provider to omninode.yaml. OpenAI-compatible gateways (including OpenRouter and local runtimes) are supported today; OmniHilbras gets its own adapter in Phase 2."
+  ).requiredOption("--name <name>", "Unique provider name used in configuration and the model registry.").requiredOption("--base-url <url>", "Provider base URL, e.g. https://example.com/v1").option(
+    "--type <type>",
+    "Provider type: openai-compatible, omnihilbras, openrouter, local or custom.",
+    "openai-compatible"
+  ).option(
+    "--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("remove <name>").description("Remove a provider (planned for Phase 1 follow-up).").action(() => {
+    throw notImplemented("omninode provider remove", "a Phase 1 follow-up");
   });
 }
-function notImplemented(command, phase) {
-  return new OmniNodeError(
-    "NOT_IMPLEMENTED",
-    `${command} is planned for ${phase}. Edit omninode.yaml directly for now.`
-  );
+async function addProvider(options) {
+  const configPath = findConfigFile();
+  if (!configPath) {
+    throw new OmniNodeError("CONFIG_NOT_FOUND", "No omninode.yaml found. Run `omninode init` first.");
+  }
+  const candidate = providerConfigSchema.safeParse({
+    name: options.name,
+    type: options.type,
+    base_url: options.baseUrl,
+    ...options.apiKeyEnvVar !== void 0 ? { api_key_env_var: options.apiKeyEnvVar } : {}
+  });
+  if (!candidate.success) {
+    const issues = candidate.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+    throw new OmniNodeError("CLI_USAGE", `Invalid provider options: ${issues}`);
+  }
+  const newProvider = candidate.data;
+  const existing = loadConfig();
+  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}`
+    );
+  }
+  writeFileSync2(configPath, doc.toString(), "utf8");
+  console.log(`Added provider "${newProvider.name}" (${newProvider.type}) to ${configPath}.`);
+  if (newProvider.api_key_env_var) {
+    console.log(
+      `Set $${newProvider.api_key_env_var} in your environment, then run: omninode provider test ${newProvider.name}`
+    );
+  } else {
+    console.log(`Run \`omninode provider test ${newProvider.name}\` to verify connectivity.`);
+  }
+}
+async function testProvider(name) {
+  const config = loadConfig();
+  const providerConfig = config.project.providers.find((p) => p.name === name);
+  if (!providerConfig) {
+    const available = config.project.providers.map((p) => p.name).join(", ") || "(none)";
+    throw new ProviderError(
+      "PROVIDER_NOT_FOUND",
+      `Provider "${name}" is not configured. Configured providers: ${available}.`
+    );
+  }
+  const provider = createProvider(providerConfig);
+  console.log(`Testing provider "${name}" (${providerConfig.type}) at ${provider.config.baseUrl}`);
+  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}`);
+  if (!health.connected) process.exitCode = 1;
+}
+
+// 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/models.ts
+var CAPABILITIES = [
+  "chat",
+  "coding",
+  "tools",
+  "vision",
+  "embeddings"
+];
+function registerModelsCommand(program) {
+  program.command("models").description("Discover and list models from configured providers (model registry, \xA78).").argument("[provider]", "Only discover from this provider.").option("-c, --capability <capability>", `Filter by capability: ${CAPABILITIES.join(", ")}.`).action(async (providerName, options) => {
+    const capability = options.capability;
+    if (capability !== void 0 && !CAPABILITIES.includes(capability)) {
+      throw new OmniNodeError(
+        "CLI_USAGE",
+        `Unknown capability "${options.capability}". Valid capabilities: ${CAPABILITIES.join(", ")}.`
+      );
+    }
+    const config = loadConfig();
+    const selected = config.project.providers.filter(
+      (p) => providerName ? p.name === providerName : true
+    );
+    if (selected.length === 0) {
+      throw new OmniNodeError(
+        "PROVIDER_NOT_FOUND",
+        providerName ? `Provider "${providerName}" is not configured.` : "No providers configured. Add one with `omninode provider add`."
+      );
+    }
+    const registry = new ModelRegistry();
+    for (const providerConfig of selected) {
+      try {
+        const provider = createProvider(providerConfig);
+        const discovered = await registry.discoverFrom(provider);
+        console.log(`${providerConfig.name}: ${discovered.length} model(s)`);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.log(`${providerConfig.name}: discovery failed \u2014 ${message}`);
+      }
+    }
+    const models = registry.list({
+      ...providerName !== void 0 ? { provider: providerName } : {},
+      ...capability !== void 0 ? { capability } : {}
+    });
+    if (models.length === 0) {
+      console.log("No models found.");
+      return;
+    }
+    console.log("");
+    for (const model of models) {
+      console.log(`${model.provider}:${model.id}`);
+    }
+  });
 }
 
 // src/cli/commands/agents.ts
@@ -345,6 +808,7 @@ function createProgram() {
   registerRoleCommands(program);
   registerTaskCommands(program);
   registerReportCommands(program);
+  registerModelsCommand(program);
   return program;
 }
 async function run(argv) {