@hilbras/omninode 2.0.0-alpha.5 → 2.0.0-alpha.7

package/README.md

@@ -18,9 +18,9 @@ existing intelligence; it does not try to become another model.
 
 ## Status
 
-**v2.0.0-alpha.5 — v2 Phase 5: Pipeline Lifecycle v2**
+**v2.0.0-alpha.7 — v2 Phase 7: OmniHilbras Integration v2**
 (the reliability & interoperability line: architecture → execution →
-protocol → adapters → pipelines) (the v2
+protocol → adapters → pipelines → providers → OmniHilbras) (the v2
 roadmap is [docs/ROADMAP_V2.md](docs/ROADMAP_V2.md); the v1 plan is complete:
 the
 full loop from §28 runs in one command —
@@ -31,6 +31,20 @@ for the plan and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design).
 
 ### What's new in v2 (so far)
 
+- **Phase 7 — OmniHilbras Integration v2**: the dedicated adapter now
+  captures gateway-level metadata (version, tier, region) and attaches it
+  to discovered models, honors provider-level `timeout_ms`, and supports
+  streaming completions (`stream()` over SSE) — while a guard test proves
+  the core references OmniHilbras *only* through the provider layer, and a
+  full pipeline runs with no OmniHilbras configured at all.
+- **Phase 6 — Provider Infrastructure v2**: standardized provider contract
+  (`providerId`, secret-free `authentication`, declared `capabilities`,
+  `connect()` / `getModel()` discovery), richer model metadata (context
+  window, input/output modalities, tool/vision/structured-output/streaming
+  support), and **unified error normalization** — every provider failure now
+  carries a stable `kind` (auth, rate limit, invalid request, model not
+  found, timeout, network, server, unknown) plus `retryable` and
+  `retryAfterMs`. Details: [PROVIDERS.md](docs/PROVIDERS.md).
 - **Phase 5 — Pipeline Lifecycle**: first-class pipeline cancellation
   (`omninode pipeline cancel <run-id>`: stop scheduling → cancel running
   tasks → terminate agent processes → persist a `cancelled` run), `pipeline
@@ -319,7 +333,7 @@ required for the core engine.
 - [Architecture](docs/ARCHITECTURE.md) — module map, workflow, local state
 - [Security model](docs/SECURITY.md) — secrets, process execution, env isolation, audit log
 - [API stability policy](docs/API_STABILITY.md) and [public API inventory](docs/API.md)
-- [Agent Protocol v2 spec](docs/PROTOCOL.md) · [Deprecations](docs/DEPRECATIONS.md) · [Changelog](CHANGELOG.md) · [v2 roadmap](docs/ROADMAP_V2.md)
+- [Agent Protocol v2 spec](docs/PROTOCOL.md) · [Providers](docs/PROVIDERS.md) · [Deprecations](docs/DEPRECATIONS.md) · [Changelog](CHANGELOG.md) · [v2 roadmap](docs/ROADMAP_V2.md)
 - [Example project](examples/demo/) — a runnable end-to-end demo (`./demo.sh`)
 
 Prefer a container? `docker build -t omninode .` then

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.5";
+var OMNINODE_VERSION = "2.0.0-alpha.7";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -68,6 +68,7 @@ var providerConfigSchema = z.object({
   type: z.enum(["openai-compatible", "omnihilbras", "openrouter", "local", "custom"]),
   base_url: z.string().url(),
   api_key_env_var: z.string().min(1).optional(),
+  timeout_ms: z.number().int().positive().optional(),
   headers: z.record(z.string()).optional(),
   enabled: z.boolean().optional(),
   metadata: z.record(z.unknown()).optional()
@@ -132,7 +133,8 @@ var projectConfigSchema = z.object({
   memory: z.object({
     provider: z.string().min(1).default("local"),
     base_url: z.string().url().optional(),
-    api_key_env_var: z.string().min(1).optional()
+    api_key_env_var: z.string().min(1).optional(),
+    timeout_ms: z.number().int().positive().optional()
   }).strict().optional()
 }).strict();
 var appConfigSchema = z.object({
@@ -245,6 +247,7 @@ function toProviderConfig(raw) {
     type: raw.type,
     baseUrl: raw.base_url,
     apiKeyEnvVar: raw.api_key_env_var,
+    timeoutMs: raw.timeout_ms,
     headers: raw.headers,
     enabled: raw.enabled,
     metadata: raw.metadata
@@ -363,35 +366,32 @@ function authHeaders(config, env = process.env) {
 }
 
 // src/providers/http.ts
+var HttpResponseError = class extends Error {
+  constructor(message, status, cause) {
+    super(message, { cause });
+    this.status = status;
+    this.name = "HttpResponseError";
+  }
+  status;
+};
 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
-    });
-  }
+  const 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)
+  });
   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 }
-    });
+    throw new HttpResponseError(`Response from ${url} was not valid JSON.`, response.status, error);
   }
   return { status: response.status, body: parsed };
 }
@@ -452,24 +452,167 @@ var Logger = class _Logger {
 };
 var logger = new Logger();
 
+// src/providers/errors.ts
+function kindToCode(kind) {
+  switch (kind) {
+    case "AUTHENTICATION_ERROR":
+      return "PROVIDER_AUTH_FAILED";
+    case "MODEL_NOT_FOUND":
+      return "MODEL_NOT_FOUND";
+    default:
+      return "PROVIDER_UNAVAILABLE";
+  }
+}
+function isRetryable(kind) {
+  return kind === "RATE_LIMIT_ERROR" || kind === "SERVER_ERROR" || kind === "NETWORK_ERROR";
+}
+function kindFromStatus(status) {
+  if (status === 401 || status === 403) return "AUTHENTICATION_ERROR";
+  if (status === 429) return "RATE_LIMIT_ERROR";
+  if (status === 404) return "MODEL_NOT_FOUND";
+  if (status === 408 || status === 504) return "TIMEOUT";
+  if (status >= 500) return "SERVER_ERROR";
+  if (status >= 400) return "INVALID_REQUEST";
+  return "UNKNOWN_ERROR";
+}
+function extractMessage(body) {
+  if (body === null || typeof body !== "object") return void 0;
+  const root = body;
+  const error = root.error ?? root;
+  const message = error.message ?? error.detail ?? root.message;
+  return typeof message === "string" ? message : void 0;
+}
+function parseRetryAfter(value, now = Date.now()) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - now);
+}
+function isTimeoutError(error) {
+  return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError") || typeof error?.code === "string" && error.code === "ABORT_ERR";
+}
+function fallbackMessage(kind, context, status) {
+  const { provider, operation } = context;
+  switch (kind) {
+    case "AUTHENTICATION_ERROR":
+      return `Authentication with provider "${provider}" failed (HTTP ${status}). Check that the referenced API key is set and valid.`;
+    case "RATE_LIMIT_ERROR":
+      return `Provider "${provider}" rate-limited ${operation} (HTTP ${status}). Retry later.`;
+    case "MODEL_NOT_FOUND":
+      return `Provider "${provider}" does not expose the requested model (HTTP ${status}).`;
+    case "TIMEOUT":
+      return `Provider "${provider}" timed out during ${operation} (HTTP ${status}).`;
+    case "SERVER_ERROR":
+      return `Provider "${provider}" returned a server error during ${operation} (HTTP ${status}).`;
+    case "INVALID_REQUEST":
+      return `Provider "${provider}" rejected ${operation} as invalid (HTTP ${status}).`;
+    default:
+      return `Provider "${provider}" failed during ${operation} (HTTP ${status}).`;
+  }
+}
+function providerHttpError(context) {
+  const status = context.status ?? 0;
+  const kind = kindFromStatus(status);
+  const detail = extractMessage(context.body);
+  const retryAfterMs = context.retryAfterMs ?? parseRetryAfter(void 0);
+  return new ProviderError(
+    context.code ?? kindToCode(kind),
+    detail ?? fallbackMessage(kind, context, status),
+    {
+      cause: context.cause,
+      details: {
+        kind,
+        provider: context.provider,
+        operation: context.operation,
+        status,
+        retryable: isRetryable(kind),
+        ...retryAfterMs !== void 0 ? { retryAfterMs } : {},
+        ...detail ? { providerMessage: detail } : {}
+      }
+    }
+  );
+}
+function providerTransportError(context) {
+  const cause = context.cause;
+  const kind = isTimeoutError(cause) ? "TIMEOUT" : cause instanceof SyntaxError || cause?.name === "HttpResponseError" ? "UNKNOWN_ERROR" : "NETWORK_ERROR";
+  const message = context.cause instanceof Error ? context.cause.message : String(context.cause);
+  return new ProviderError("PROVIDER_UNAVAILABLE", `Provider request failed: ${message}`, {
+    cause: context.cause,
+    details: {
+      kind,
+      provider: context.provider,
+      operation: context.operation,
+      retryable: isRetryable(kind)
+    }
+  });
+}
+
 // src/providers/openai-compatible/index.ts
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 var OpenAICompatibleProvider = class {
   config;
+  providerId;
+  authentication;
   log;
-  constructor(config, log = logger) {
+  /** Discovered models, so getModel() answers without another round-trip. */
+  discovered;
+  env;
+  constructor(config, log = logger, env = process.env) {
     this.config = { ...config, baseUrl: normalizeBaseUrl(config.baseUrl) };
+    this.env = env;
+    this.providerId = config.providerId ?? config.name;
+    this.authentication = {
+      method: config.apiKeyEnvVar ? "bearer" : "none",
+      ...config.apiKeyEnvVar ? { envVar: config.apiKeyEnvVar } : {},
+      configured: config.apiKeyEnvVar ? Boolean(env[config.apiKeyEnvVar]) : true
+    };
     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);
+  /** Provider-level request timeout (roadmap §6.6/§11) with the shared default. */
+  get requestTimeoutMs() {
+    return this.config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+  /** Authenticate + discover (roadmap §10, Model Discovery). */
+  async connect() {
+    authHeaders(this.config, this.env);
+    const models = await this.listModels();
+    this.discovered = models;
+    return models;
+  }
+  async getModel(modelId) {
+    const models = this.discovered ?? await this.connect();
+    return models.find((m) => m.id === modelId);
+  }
+  /** Raw /models body (protected so adapters can capture gateway-level metadata). */
+  async rawModelsResponse() {
+    const response = await this.modelsRequest();
+    return response.body;
+  }
+  async modelsRequest() {
+    let response;
+    try {
+      response = await requestJson(`${this.config.baseUrl}/models`, {
+        headers: authHeaders(this.config, this.env),
+        timeoutMs: this.requestTimeoutMs
+      });
+    } catch (error) {
+      if (error instanceof ProviderError) throw error;
+      throw providerTransportError({ provider: this.config.name, operation: "listModels", cause: error });
     }
+    const { status, body } = response;
     if (status !== 200) {
-      throw unavailable(this.config, `Model discovery returned HTTP ${status}.`, status);
+      throw providerHttpError({
+        provider: this.config.name,
+        operation: "listModels",
+        status,
+        body
+      });
     }
+    return response;
+  }
+  async listModels() {
+    const body = await this.rawModelsResponse();
     const entries = extractModelEntries(body, this.config);
     const models = [];
     let skipped = 0;
@@ -478,22 +621,44 @@ var OpenAICompatibleProvider = class {
         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 } : {}
-        }
-      });
+      models.push(this.toModelInfo(entry2));
     }
     if (skipped > 0) {
       this.log.warn(`Skipped ${skipped} model entr(y/ies) without a valid id.`);
     }
     return models;
   }
+  /** Maps a raw model entry onto the normalized metadata shape (§10). */
+  toModelInfo(entry2) {
+    const parameters = Array.isArray(entry2.supported_parameters) ? entry2.supported_parameters.filter((p) => typeof p === "string") : void 0;
+    const contextWindow = typeof entry2.context_length === "number" ? entry2.context_length : typeof entry2.context_window === "number" ? entry2.context_window : void 0;
+    const inputTypes = normalizeModalities(entry2.input_modalities);
+    const outputTypes = normalizeModalities(entry2.output_modalities);
+    return {
+      provider: this.config.name,
+      id: entry2.id,
+      displayName: entry2.id,
+      ...typeof entry2.name === "string" ? { name: entry2.name } : {},
+      status: "available",
+      ...contextWindow !== void 0 ? { contextWindow } : {},
+      ...inputTypes !== void 0 ? { inputTypes } : {},
+      ...outputTypes !== void 0 ? { outputTypes } : {},
+      ...parameters !== void 0 ? {
+        supportsTools: parameters.includes("tools") || parameters.includes("tool_choice"),
+        supportsStructuredOutput: parameters.includes("response_format"),
+        supportsStreaming: parameters.includes("stream")
+      } : {},
+      metadata: {
+        ...typeof entry2.owned_by === "string" ? { ownedBy: entry2.owned_by } : {},
+        ...typeof entry2.created === "number" ? { createdAt: entry2.created } : {},
+        ...parameters !== void 0 ? { supportedParameters: parameters } : {}
+      }
+    };
+  }
+  /** Streaming where the gateway supports it (§11). */
+  stream(request, onChunk) {
+    return streamChatCompletion(this.config, request, onChunk, this.env);
+  }
   async healthCheck() {
     const lastCheckedAt = (/* @__PURE__ */ new Date()).toISOString();
     try {
@@ -523,27 +688,35 @@ var OpenAICompatibleProvider = class {
     }
   }
   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 } }
-      );
+    let response;
+    try {
+      response = await requestJson(`${this.config.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: authHeaders(this.config, this.env),
+        timeoutMs: this.requestTimeoutMs,
+        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 } : {}
+        }
+      });
+    } catch (error) {
+      if (error instanceof ProviderError) throw error;
+      throw providerTransportError({ provider: this.config.name, operation: "chat", cause: error });
     }
+    const { status, body } = response;
     if (status !== 200) {
-      throw unavailable(this.config, `Chat completion returned HTTP ${status}.`, status);
+      throw providerHttpError({
+        provider: this.config.name,
+        operation: "chat",
+        status,
+        body,
+        ...status === 404 ? {
+          code: "MODEL_NOT_FOUND"
+        } : {}
+      });
     }
     const payload = body;
     const choices = Array.isArray(payload.choices) ? payload.choices : [];
@@ -565,6 +738,81 @@ var OpenAICompatibleProvider = class {
     };
   }
 };
+async function streamChatCompletion(config, request, onChunk, env = process.env) {
+  const baseUrl = normalizeBaseUrl(config.baseUrl);
+  const timeoutMs = config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  let response;
+  try {
+    response = await fetch(`${baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        accept: "text/event-stream",
+        "content-type": "application/json",
+        ...authHeaders(config, env)
+      },
+      body: JSON.stringify({
+        model: request.model,
+        messages: request.messages,
+        stream: true,
+        ...request.temperature !== void 0 ? { temperature: request.temperature } : {},
+        ...request.maxTokens !== void 0 ? { max_tokens: request.maxTokens } : {}
+      }),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  } catch (error) {
+    throw providerTransportError({ provider: config.name, operation: "stream", cause: error });
+  }
+  if (!response.ok) {
+    const body = await response.json().catch(() => void 0);
+    throw providerHttpError({ provider: config.name, operation: "stream", status: response.status, body });
+  }
+  if (!response.body) {
+    throw providerHttpError({
+      provider: config.name,
+      operation: "stream",
+      status: 500,
+      body: { error: { message: "streaming is not supported by this endpoint" } }
+    });
+  }
+  let content = "";
+  let model = request.model;
+  let finishReason;
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const piece of response.body) {
+    buffer += decoder.decode(piece, { stream: true });
+    let newline = buffer.indexOf("\n");
+    while (newline >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      newline = buffer.indexOf("\n");
+      if (line.length === 0 || line.startsWith(":")) continue;
+      const data = line.startsWith("data:") ? line.slice(5).trim() : line;
+      if (data === "[DONE]") continue;
+      let event;
+      try {
+        event = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      if (typeof event.model === "string") model = event.model;
+      const choices = Array.isArray(event.choices) ? event.choices : [];
+      const first = choices[0];
+      const delta = typeof first?.delta?.content === "string" ? first.delta.content : "";
+      if (delta.length > 0) content += delta;
+      if (typeof first?.finish_reason === "string") finishReason = first.finish_reason;
+      onChunk({ delta, ...finishReason !== void 0 ? { finishReason } : {}, raw: event });
+    }
+  }
+  return { model, content, ...finishReason !== void 0 ? { finishReason } : {} };
+}
+function normalizeModalities(value) {
+  const list = Array.isArray(value) ? value : typeof value === "string" ? [value] : void 0;
+  if (!list) return void 0;
+  const allowed = /* @__PURE__ */ new Set(["text", "image", "audio", "video", "embedding"]);
+  const modalities = list.filter((m) => typeof m === "string" && allowed.has(m));
+  return modalities.length > 0 ? modalities : void 0;
+}
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
@@ -579,14 +827,6 @@ function extractModelEntries(body, config) {
     { 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 }
@@ -599,11 +839,33 @@ function inferHealth(error) {
 
 // src/providers/omnihilbras/index.ts
 var OmniHilbrasProvider = class extends OpenAICompatibleProvider {
+  gateway;
+  async listModels() {
+    const raw = await this.rawModelsResponse();
+    await this.extractGatewayMetadata(raw);
+    const models = await super.listModels();
+    return this.gateway ? models.map((model) => ({ ...model, metadata: { ...model.metadata, gateway: this.gateway } })) : models;
+  }
   /**
    * Run the full connect flow. Throws on authentication or transport failure
    * (use healthCheck() for a non-throwing probe).
    */
-  async connect(registry) {
+  /**
+   * Gateway metadata reported alongside the model list (gateway version, tier,
+   * region…), kept separate from per-model metadata (§11 — provider metadata).
+   */
+  gatewayMetadata() {
+    return this.gateway;
+  }
+  async extractGatewayMetadata(body) {
+    if (body !== null && typeof body === "object") {
+      const gateway = body.gateway;
+      if (gateway !== null && typeof gateway === "object") {
+        this.gateway = gateway;
+      }
+    }
+  }
+  async connectAndRegister(registry) {
     const apiKey = resolveApiKey(this.config);
     const discovered = await this.listModels();
     const seen = /* @__PURE__ */ new Set();
@@ -827,7 +1089,7 @@ async function testProvider(name, options = {}) {
   if (options.connect && provider instanceof OmniHilbrasProvider) {
     const registry = new ModelRegistry();
     try {
-      const result = await provider.connect(registry);
+      const result = await provider.connectAndRegister(registry);
       printProviderStatus(result.status);
       console.log(`  registered: ${result.registered}`);
     } catch (error) {