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

package/README.md

@@ -18,9 +18,9 @@ existing intelligence; it does not try to become another model.
 
 ## Status
 
-**v2.0.0-alpha.7 — v2 Phase 7: OmniHilbras Integration v2**
+**v2.0.0-alpha.9 — v2 Phase 9: Report System v2**
 (the reliability & interoperability line: architecture → execution →
-protocol → adapters → pipelines → providers → OmniHilbras) (the v2
+protocol → adapters → pipelines → providers → OmniHilbras → memory → reports) (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,19 @@ for the plan and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design).
 
 ### What's new in v2 (so far)
 
+- **Phase 9 — Report System v2**: reports are validated machine-readable
+  objects — `validateReport()` runs on everything entering the system and
+  malformed reports are rejected with diagnostics instead of poisoning
+  aggregation. Findings gain description/confidence/source/recommendation,
+  evidence is typed (`file`, `line`, `url`, `command`, `observation`,
+  `artifact`), and reports carry artifacts and run provenance.
+  Details: [REPORTS.md](docs/REPORTS.md).
+- **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
@@ -333,7 +346,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) · [Reports](docs/REPORTS.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.7";
+var OMNINODE_VERSION = "2.0.0-alpha.9";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -134,7 +134,8 @@ var projectConfigSchema = z.object({
     provider: z.string().min(1).default("local"),
     base_url: z.string().url().optional(),
     api_key_env_var: z.string().min(1).optional(),
-    timeout_ms: z.number().int().positive().optional()
+    /** When true, memory failures fail tasks instead of being tolerated (§12). */
+    required: z.boolean().optional()
   }).strict().optional()
 }).strict();
 var appConfigSchema = z.object({
@@ -216,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
         }
       } : {}
     },
@@ -2490,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",
@@ -2552,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) {
@@ -2563,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 = {
@@ -2594,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}.`);
@@ -2609,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}.`);
@@ -2644,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 } : {}
     };
@@ -2674,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}`,
@@ -2735,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 };
   }
 };
 
@@ -2780,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
   });
@@ -2894,6 +2997,84 @@ function truncate2(text, max) {
 
 // src/reports/aggregate.ts
 import { randomBytes as randomBytes2 } from "crypto";
+
+// src/reports/schema.ts
+import { z as z2 } from "zod";
+var evidenceSchema = z2.union([
+  z2.string().transform((excerpt) => ({ kind: "observation", excerpt })),
+  z2.object({
+    kind: z2.enum(["file", "line", "url", "command", "observation", "artifact"]),
+    ref: z2.string().optional(),
+    line: z2.number().int().optional(),
+    excerpt: z2.string().optional(),
+    agent: z2.string().optional()
+  })
+]);
+var findingSchema = z2.object({
+  id: z2.string().min(1),
+  title: z2.string().min(1),
+  detail: z2.string().default(""),
+  description: z2.string().optional(),
+  severity: z2.enum(["info", "low", "medium", "high", "critical"]).optional(),
+  confidence: z2.enum(["low", "medium", "high"]).optional(),
+  evidence: z2.array(evidenceSchema).optional(),
+  location: z2.string().optional(),
+  tags: z2.array(z2.string()).optional(),
+  source: z2.object({ agent: z2.string().optional(), reportId: z2.string().optional(), pipelineRunId: z2.string().optional() }).optional(),
+  recommendation: z2.string().optional()
+});
+var artifactSchema = z2.object({
+  kind: z2.enum(["file", "patch", "log", "screenshot", "document", "data"]),
+  ref: z2.string().min(1),
+  description: z2.string().optional(),
+  mediaType: z2.string().optional(),
+  bytes: z2.number().int().optional()
+});
+var reportSchema = z2.object({
+  id: z2.string().min(1),
+  taskId: z2.string().min(1),
+  agent: z2.string().min(1),
+  agentId: z2.string().optional(),
+  pipelineRunId: z2.string().optional(),
+  model: z2.string().optional(),
+  summary: z2.string(),
+  findings: z2.array(findingSchema),
+  recommendations: z2.array(z2.string()),
+  confidence: z2.enum(["low", "medium", "high"]).optional(),
+  evidence: z2.array(evidenceSchema).optional(),
+  artifacts: z2.array(artifactSchema).optional(),
+  createdAt: z2.string().min(1),
+  metadata: z2.record(z2.unknown()).optional()
+});
+function validateReport(value) {
+  const parsed = reportSchema.safeParse(value);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => ({
+      path: issue.path.join(".") || "(root)",
+      message: issue.message
+    }));
+    return {
+      valid: false,
+      issues,
+      reason: `report failed schema validation (${issues.length} issue(s))`
+    };
+  }
+  const report = parsed.data;
+  report.findings = report.findings.map((finding) => ({
+    ...finding,
+    description: finding.description ?? finding.detail,
+    ...finding.source === void 0 ? { source: { agent: report.agent, reportId: report.id, ...report.pipelineRunId !== void 0 ? { pipelineRunId: report.pipelineRunId } : {} } } : {}
+  }));
+  return { valid: true, report };
+}
+function normalizeEvidence(input) {
+  if (input === void 0) return void 0;
+  return input.map(
+    (item) => typeof item === "string" ? { kind: "observation", excerpt: item } : item
+  );
+}
+
+// src/reports/aggregate.ts
 var SEVERITY_RANK = {
   info: 0,
   low: 1,
@@ -2940,7 +3121,7 @@ function mergeFinding(groups, finding, report, threshold) {
     group.occurrences += 1;
     group.details.push(finding.detail);
     group.sources.push(source);
-    group.evidence.push(...finding.evidence ?? []);
+    group.evidence.push(...normalizeEvidence(finding.evidence) ?? []);
     if (finding.severity && (!group.severity || SEVERITY_RANK[finding.severity] > SEVERITY_RANK[group.severity])) {
       group.severity = finding.severity;
     }
@@ -2952,7 +3133,7 @@ function mergeFinding(groups, finding, report, threshold) {
     sources: [source],
     occurrences: 1,
     ...finding.severity ? { severity: finding.severity } : {},
-    evidence: [...finding.evidence ?? []]
+    evidence: [...normalizeEvidence(finding.evidence) ?? []]
   });
 }
 function mergeRecommendation(groups, text, report, threshold) {
@@ -3034,6 +3215,7 @@ function extractReportFromText(raw, meta) {
     id: `${meta.taskId}-f-${index + 1}`,
     title: truncate4(text, 120),
     detail: text,
+    description: text,
     severity: guessSeverity(text)
   }));
   return {
@@ -3044,7 +3226,8 @@ function extractReportFromText(raw, meta) {
     summary,
     findings,
     recommendations: recommendationTexts.map((t) => truncate4(t, 200)),
-    metadata: evidenceTexts.length > 0 ? { evidence: evidenceTexts } : void 0,
+    ...evidenceTexts.length > 0 ? { evidence: evidenceTexts.map((excerpt) => ({ kind: "observation", excerpt })) } : {},
+    metadata: evidenceTexts.length > 0 ? { evidenceCount: evidenceTexts.length } : void 0,
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
@@ -3060,27 +3243,46 @@ var ReportService = class {
   }
   store;
   log;
+  /** Rejected reports from the last collection (§13 — malformed never enters aggregation). */
+  lastDiagnostics = { collected: 0, accepted: 0, rejected: [] };
   get storeRef() {
     return this.store;
   }
-  /** Normalizes finished tasks into reports (§17 — normalizer). */
+  /** Normalizes finished tasks into reports (§17 — normalizer), validating each
+   *  one so malformed reports never reach aggregation (§13). */
   async collectFromTasks(tasks) {
-    const reports = [];
+    const candidates = [];
     for (const task of tasks) {
       const structured = task.result?.reports ?? [];
       if (structured.length > 0) {
-        reports.push(...structured);
+        candidates.push(...structured);
         continue;
       }
       const text = task.result?.rawOutput ?? task.result?.summary ?? "";
       if (text.trim().length === 0) continue;
-      reports.push(
+      candidates.push(
         extractReportFromText(text, {
           taskId: task.id,
           agent: task.agent ?? "unknown"
         })
       );
     }
+    const reports = [];
+    const rejected = [];
+    for (const candidate of candidates) {
+      const result = validateReport(candidate);
+      if (result.valid) {
+        reports.push(result.report);
+      } else {
+        rejected.push({
+          key: candidate?.id ?? "(unknown)",
+          reason: result.reason,
+          issues: result.issues.map((issue) => `${issue.path}: ${issue.message}`)
+        });
+        this.log.warn(`Rejected malformed report: ${result.reason}`);
+      }
+    }
+    this.lastDiagnostics = { collected: candidates.length, accepted: reports.length, rejected };
     return reports;
   }
   async saveReports(reports) {
@@ -3300,7 +3502,7 @@ function truncate5(text, max) {
 
 // src/planner/model.ts
 import { randomBytes as randomBytes4 } from "crypto";
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/planner/context.ts
 function buildPlannerContext(request) {
@@ -3353,21 +3555,21 @@ ${request.context}`);
 }
 
 // src/planner/model.ts
-var planStepJsonSchema = z2.object({
-  id: z2.string().optional(),
-  title: z2.string().min(1),
-  description: z2.string().optional(),
-  order: z2.number().int().optional(),
-  targets: z2.array(z2.string()).optional(),
-  acceptance_criteria: z2.array(z2.string()).optional(),
-  depends_on: z2.array(z2.string()).optional(),
-  source_findings: z2.array(z2.string()).optional()
+var planStepJsonSchema = z3.object({
+  id: z3.string().optional(),
+  title: z3.string().min(1),
+  description: z3.string().optional(),
+  order: z3.number().int().optional(),
+  targets: z3.array(z3.string()).optional(),
+  acceptance_criteria: z3.array(z3.string()).optional(),
+  depends_on: z3.array(z3.string()).optional(),
+  source_findings: z3.array(z3.string()).optional()
 }).strict();
-var planJsonSchema = z2.object({
-  summary: z2.string().min(1),
-  steps: z2.array(planStepJsonSchema).min(1),
-  risks: z2.array(z2.string()).optional(),
-  notes: z2.array(z2.string()).optional()
+var planJsonSchema = z3.object({
+  summary: z3.string().min(1),
+  steps: z3.array(planStepJsonSchema).min(1),
+  risks: z3.array(z3.string()).optional(),
+  notes: z3.array(z3.string()).optional()
 }).strict();
 var ModelPlanner = class {
   constructor(options) {
@@ -4056,7 +4258,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
   });