@hilbras/omninode 2.0.0-alpha.6 → 2.0.0-alpha.8

package/README.md

@@ -18,9 +18,9 @@ existing intelligence; it does not try to become another model.
 
 ## Status
 
-**v2.0.0-alpha.6 — v2 Phase 6: Provider Infrastructure v2**
+**v2.0.0-alpha.8 — v2 Phase 8: Remembera Integration v2**
 (the reliability & interoperability line: architecture → execution →
-protocol → adapters → pipelines → providers) (the v2
+protocol → adapters → pipelines → providers → OmniHilbras → memory) (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,18 @@ for the plan and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design).
 
 ### What's new in v2 (so far)
 
+- **Phase 8 — Remembera / Memory v2**: the memory contract is formalized
+  (`retrieve` / `store` / `search` / `metadata` with v1 `query` / `write`
+  aliases kept working), memory gains structured **categories** (decisions,
+  problems, conventions, tasks…), retrieval is **task-oriented and budgeted**
+  (never "load all memory"), and `memory.required: true` makes backend
+  failures fatal instead of tolerated. Details: [MEMORY.md](docs/MEMORY.md).
+- **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
@@ -327,7 +339,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) · [Providers](docs/PROVIDERS.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) · [Memory](docs/MEMORY.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.6";
+var OMNINODE_VERSION = "2.0.0-alpha.8";
 
 // 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,9 @@ 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(),
+    /** When true, memory failures fail tasks instead of being tolerated (§12). */
+    required: z.boolean().optional()
   }).strict().optional()
 }).strict();
 var appConfigSchema = z.object({
@@ -214,7 +217,8 @@ function toAppConfig(yaml) {
         memory: {
           provider: yaml.project.memory.provider,
           baseUrl: yaml.project.memory.base_url,
-          apiKeyEnvVar: yaml.project.memory.api_key_env_var
+          apiKeyEnvVar: yaml.project.memory.api_key_env_var,
+          required: yaml.project.memory.required
         }
       } : {}
     },
@@ -245,6 +249,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
@@ -546,6 +551,7 @@ function providerTransportError(context) {
 }
 
 // src/providers/openai-compatible/index.ts
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 var OpenAICompatibleProvider = class {
   config;
   providerId;
@@ -565,6 +571,10 @@ var OpenAICompatibleProvider = class {
     };
     this.log = log.child({ provider: config.name });
   }
+  /** 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);
@@ -576,11 +586,17 @@ var OpenAICompatibleProvider = class {
     const models = this.discovered ?? await this.connect();
     return models.find((m) => m.id === modelId);
   }
-  async listModels() {
+  /** 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)
+        headers: authHeaders(this.config, this.env),
+        timeoutMs: this.requestTimeoutMs
       });
     } catch (error) {
       if (error instanceof ProviderError) throw error;
@@ -595,6 +611,10 @@ var OpenAICompatibleProvider = class {
         body
       });
     }
+    return response;
+  }
+  async listModels() {
+    const body = await this.rawModelsResponse();
     const entries = extractModelEntries(body, this.config);
     const models = [];
     let skipped = 0;
@@ -637,6 +657,10 @@ var OpenAICompatibleProvider = class {
       }
     };
   }
+  /** 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 {
@@ -671,6 +695,7 @@ var OpenAICompatibleProvider = class {
       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,
@@ -715,6 +740,74 @@ 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;
@@ -748,10 +841,32 @@ 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).
    */
+  /**
+   * 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();
@@ -2377,6 +2492,23 @@ var FileAuditLog = class {
   }
 };
 
+// src/memory/base.ts
+function defaultSearch(provider, text, options = {}) {
+  return provider.retrieve({
+    text,
+    ...options.scope !== void 0 ? { scope: options.scope } : {},
+    ...options.limit !== void 0 ? { limit: options.limit } : {}
+  });
+}
+function defaultMetadata(name, options = {}) {
+  return {
+    name,
+    capabilities: options.capabilities ?? ["retrieve", "store", "search"],
+    relevanceRanking: options.relevanceRanking ?? false,
+    ...options.backend !== void 0 ? { backend: options.backend } : {}
+  };
+}
+
 // src/memory/local.ts
 var STOPWORDS = /* @__PURE__ */ new Set([
   "the",
@@ -2439,9 +2571,27 @@ var LocalMemoryProvider = class extends JsonFileStore {
   constructor(directory) {
     super({ ...directory !== void 0 ? { directory } : {}, fileName: "memory.json" });
   }
-  async query(query) {
+  metadata() {
+    return defaultMetadata(this.name, {
+      capabilities: ["retrieve", "store", "search", "categories", "tags"],
+      relevanceRanking: true,
+      backend: { kind: "json-file", deterministicScoring: true }
+    });
+  }
+  search(text, options = {}) {
+    return defaultSearch(this, text, options);
+  }
+  /** @deprecated v1 alias of {@link retrieve}. */
+  query(query) {
+    return this.retrieve(query);
+  }
+  /** @deprecated v1 alias of {@link store}. */
+  write(entry2) {
+    return this.store(entry2);
+  }
+  async retrieve(query) {
     const entries = await this.readAll();
-    const filtered = entries.filter((entry2) => query.scope ? entry2.scope === query.scope : true).filter(
+    const filtered = entries.filter((entry2) => query.scope ? entry2.scope === query.scope : true).filter((entry2) => query.category ? entry2.category === query.category : true).filter(
       (entry2) => query.tags && query.tags.length > 0 ? query.tags.every((tag) => (entry2.tags ?? []).includes(tag)) : true
     );
     if (!query.text || query.text.trim().length === 0) {
@@ -2450,7 +2600,7 @@ var LocalMemoryProvider = class extends JsonFileStore {
     const queryKeywords = keywords(query.text);
     return filtered.map((entry2) => ({ entry: entry2, score: relevanceScore(queryKeywords, entry2) })).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score).slice(0, query.limit ?? 10).map(({ entry: entry2 }) => entry2);
   }
-  write(entry2) {
+  store(entry2) {
     return this.mutate((entries) => {
       const index = entries.findIndex((e) => e.key === entry2.key);
       const stamped = {
@@ -2481,11 +2631,40 @@ var RememberaMemoryProvider = class {
     this.env = config.env ?? process.env;
     this.log = log.child({ component: "remembera" });
   }
+  get authenticationConfigured() {
+    return this.apiKeyEnvVar === void 0 || Boolean(this.env[this.apiKeyEnvVar]);
+  }
   headers() {
     const key = this.apiKeyEnvVar ? resolveApiKey({ name: "remembera", apiKeyEnvVar: this.apiKeyEnvVar }, this.env) : void 0;
     return key ? { authorization: `Bearer ${key}` } : {};
   }
-  async query(query) {
+  /** Search delegates to the gateway's relevance query. */
+  search(text, options = {}) {
+    return defaultSearch(
+      this,
+      text,
+      {
+        ...options.scope !== void 0 ? { scope: options.scope } : {},
+        ...options.limit !== void 0 ? { limit: options.limit } : {}
+      }
+    );
+  }
+  metadata() {
+    return defaultMetadata(this.name, {
+      capabilities: ["retrieve", "store", "search", "categories", "tags"],
+      relevanceRanking: true,
+      backend: { kind: "http", baseUrl: this.baseUrl, authenticated: this.authenticationConfigured }
+    });
+  }
+  /** @deprecated v1 alias of {@link retrieve}. */
+  query(query) {
+    return this.retrieve(query);
+  }
+  /** @deprecated v1 alias of {@link store}. */
+  write(entry2) {
+    return this.store(entry2);
+  }
+  async retrieve(query) {
     const { status, body } = await this.request(`${this.baseUrl}/api/memory/query`, query);
     if (status !== 200) {
       throw new MemoryError(`Remembera query returned HTTP ${status}.`);
@@ -2496,7 +2675,7 @@ var RememberaMemoryProvider = class {
     }
     return entries.map((entry2) => this.toEntry(entry2)).filter((entry2) => entry2 !== void 0);
   }
-  async write(entry2) {
+  async store(entry2) {
     const { status } = await this.request(`${this.baseUrl}/api/memory`, entry2);
     if (status !== 200 && status !== 201) {
       throw new MemoryError(`Remembera write returned HTTP ${status}.`);
@@ -2531,6 +2710,7 @@ var RememberaMemoryProvider = class {
       content: entry2.content,
       scope: scope === "project" || scope === "role" || scope === "task" || scope === "knowledge" ? scope : "knowledge",
       ...Array.isArray(entry2.tags) ? { tags: entry2.tags.filter((t) => typeof t === "string") } : {},
+      ...typeof entry2.category === "string" ? { category: entry2.category } : {},
       ...typeof entry2.createdAt === "string" ? { createdAt: entry2.createdAt } : {},
       ...typeof entry2.updatedAt === "string" ? { updatedAt: entry2.updatedAt } : {}
     };
@@ -2561,57 +2741,54 @@ function createMemoryProvider(config) {
 }
 
 // src/memory/service.ts
+var DEFAULT_ENTRY_LIMIT = 8;
 var MAX_CONTEXT_CHARS = 4e3;
 var MemoryService = class {
-  constructor(provider, log = logger) {
+  constructor(provider, log = logger, options = {}) {
     this.provider = provider;
     this.log = log.child({ component: "memory", provider: provider.name });
+    this.required = options.required ?? false;
+    this.maxContextChars = options.maxContextChars ?? MAX_CONTEXT_CHARS;
   }
   provider;
   log;
+  required;
+  maxContextChars;
   get providerRef() {
     return this.provider;
   }
   get providerName() {
     return this.provider.name;
   }
-  /** Relevant context for a task objective; empty string when nothing matches. */
-  async gatherContext(query) {
+  get isRequired() {
+    return this.required;
+  }
+  /** Structured, budgeted context for a task (§12 — avoid loading all memory). */
+  async contextFor(query) {
+    let entries;
     try {
-      const entries = await this.provider.query({
+      entries = await this.provider.retrieve({
         text: query.objective,
         ...query.role ? { tags: [query.role] } : {},
-        limit: 8
+        limit: query.limit ?? DEFAULT_ENTRY_LIMIT
       });
-      if (entries.length === 0) return "";
-      const byScope = /* @__PURE__ */ new Map();
-      for (const entry2 of entries) {
-        byScope.set(entry2.scope, [...byScope.get(entry2.scope) ?? [], entry2]);
-      }
-      const parts = [];
-      for (const scope of ["project", "task", "role", "knowledge"]) {
-        const scopeEntries = byScope.get(scope) ?? [];
-        if (scopeEntries.length === 0) continue;
-        const lines = scopeEntries.map((entry2) => `- ${entry2.content}`).join("\n");
-        parts.push(`### Relevant memory (${scope})
-${lines}`);
-      }
-      const context = parts.join("\n\n");
-      return context.length > MAX_CONTEXT_CHARS ? `${context.slice(0, MAX_CONTEXT_CHARS)}\u2026` : context;
     } catch (error) {
-      this.log.warn(
-        `Memory query failed (continuing without memory): ${error instanceof Error ? error.message : String(error)}`
-      );
-      return "";
+      return this.handleFailure("retrieve", error, { text: "", entries: [], truncated: false });
     }
+    return this.format(entries);
   }
-  /** Records a finished task's outcome — best-effort. */
+  /** Prompt-ready context text (v1 convenience wrapper). */
+  async gatherContext(query) {
+    return (await this.contextFor(query)).text;
+  }
+  /** Records a finished task's outcome — task history plus "known problems" (§12). */
   async recordTaskOutcome(task) {
     const outcome = task.result?.summary ?? task.result?.error ?? "(no output)";
     try {
-      await this.provider.write({
+      await this.provider.store({
         key: `task:${task.id}`,
         scope: "task",
+        category: "tasks",
         content: `Objective: ${task.objective}
 Status: ${task.status}
 Outcome: ${outcome}`,
@@ -2622,18 +2799,53 @@ Outcome: ${outcome}`,
         (report) => report.findings.filter((finding) => finding.severity === "high" || finding.severity === "critical").map((finding) => ({ report, finding }))
       );
       for (const { report, finding } of significant) {
-        await this.provider.write({
+        await this.provider.store({
           key: `finding:${report.id}:${finding.id}`,
           scope: "project",
+          category: "problems",
           content: `[${finding.severity}] ${finding.title} \u2014 ${finding.detail}`,
           tags: ["known-problem", report.agent]
         });
       }
     } catch (error) {
-      this.log.warn(
-        `Memory write failed (continuing): ${error instanceof Error ? error.message : String(error)}`
+      this.handleFailure("store", error, void 0);
+    }
+  }
+  format(entries) {
+    if (entries.length === 0) return { text: "", entries, truncated: false };
+    const byScope = /* @__PURE__ */ new Map();
+    for (const entry2 of entries) {
+      byScope.set(entry2.scope, [...byScope.get(entry2.scope) ?? [], entry2]);
+    }
+    const parts = [];
+    for (const scope of ["project", "task", "role", "knowledge"]) {
+      const scopeEntries = byScope.get(scope) ?? [];
+      if (scopeEntries.length === 0) continue;
+      const lines = scopeEntries.map((entry2) => {
+        const category = entry2.category ? `[${entry2.category}] ` : "";
+        return `- ${category}${entry2.content}`;
+      }).join("\n");
+      parts.push(`### Relevant memory (${scope})
+${lines}`);
+    }
+    let text = parts.join("\n\n");
+    const truncated = text.length > this.maxContextChars;
+    if (truncated) text = `${text.slice(0, this.maxContextChars - 1)}\u2026`;
+    return { text, entries, truncated };
+  }
+  /**
+   * Failure policy (§12): continue unless memory is explicitly required.
+   */
+  handleFailure(operation, error, fallback) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (this.required) {
+      throw new MemoryError(
+        `Memory is marked required, but ${operation} failed: ${message}`,
+        { cause: error }
       );
     }
+    this.log.warn(`Memory ${operation} failed (continuing without memory): ${message}`);
+    return fallback ?? { text: "", entries: [], truncated: false };
   }
 };
 
@@ -2667,7 +2879,11 @@ function createTaskEngine(config, log = logger, directory) {
     agents,
     roles,
     store: new FileTaskStore(directory),
-    ...config.project.memory !== void 0 ? { memory: new MemoryService(createMemoryProvider(config.project.memory), log) } : {},
+    ...config.project.memory !== void 0 ? {
+      memory: new MemoryService(createMemoryProvider(config.project.memory), log, {
+        required: config.project.memory.required
+      })
+    } : {},
     audit: new FileAuditLog(),
     log
   });
@@ -3943,7 +4159,11 @@ function buildPipelineEngine(config, log = logger) {
     agents,
     roles,
     store: new FileTaskStore(),
-    ...config.project.memory !== void 0 ? { memory: new MemoryService(createMemoryProvider(config.project.memory), log) } : {},
+    ...config.project.memory !== void 0 ? {
+      memory: new MemoryService(createMemoryProvider(config.project.memory), log, {
+        required: config.project.memory.required
+      })
+    } : {},
     audit: new FileAuditLog(),
     log
   });