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

package/dist/index.js

@@ -191,7 +191,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({
@@ -273,7 +274,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
         }
       } : {}
     },
@@ -2202,6 +2204,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",
@@ -2264,9 +2283,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(entry) {
+    return this.store(entry);
+  }
+  async retrieve(query) {
     const entries = await this.readAll();
-    const filtered = entries.filter((entry) => query.scope ? entry.scope === query.scope : true).filter(
+    const filtered = entries.filter((entry) => query.scope ? entry.scope === query.scope : true).filter((entry) => query.category ? entry.category === query.category : true).filter(
       (entry) => query.tags && query.tags.length > 0 ? query.tags.every((tag) => (entry.tags ?? []).includes(tag)) : true
     );
     if (!query.text || query.text.trim().length === 0) {
@@ -2275,7 +2312,7 @@ var LocalMemoryProvider = class extends JsonFileStore {
     const queryKeywords = keywords(query.text);
     return filtered.map((entry) => ({ entry, score: relevanceScore(queryKeywords, entry) })).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score).slice(0, query.limit ?? 10).map(({ entry }) => entry);
   }
-  write(entry) {
+  store(entry) {
     return this.mutate((entries) => {
       const index = entries.findIndex((e) => e.key === entry.key);
       const stamped = {
@@ -2306,11 +2343,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(entry) {
+    return this.store(entry);
+  }
+  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}.`);
@@ -2321,7 +2387,7 @@ var RememberaMemoryProvider = class {
     }
     return entries.map((entry) => this.toEntry(entry)).filter((entry) => entry !== void 0);
   }
-  async write(entry) {
+  async store(entry) {
     const { status } = await this.request(`${this.baseUrl}/api/memory`, entry);
     if (status !== 200 && status !== 201) {
       throw new MemoryError(`Remembera write returned HTTP ${status}.`);
@@ -2356,6 +2422,7 @@ var RememberaMemoryProvider = class {
       content: entry.content,
       scope: scope === "project" || scope === "role" || scope === "task" || scope === "knowledge" ? scope : "knowledge",
       ...Array.isArray(entry.tags) ? { tags: entry.tags.filter((t) => typeof t === "string") } : {},
+      ...typeof entry.category === "string" ? { category: entry.category } : {},
       ...typeof entry.createdAt === "string" ? { createdAt: entry.createdAt } : {},
       ...typeof entry.updatedAt === "string" ? { updatedAt: entry.updatedAt } : {}
     };
@@ -2386,57 +2453,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 entry of entries) {
-        byScope.set(entry.scope, [...byScope.get(entry.scope) ?? [], entry]);
-      }
-      const parts = [];
-      for (const scope of ["project", "task", "role", "knowledge"]) {
-        const scopeEntries = byScope.get(scope) ?? [];
-        if (scopeEntries.length === 0) continue;
-        const lines = scopeEntries.map((entry) => `- ${entry.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);
+  }
+  /** Prompt-ready context text (v1 convenience wrapper). */
+  async gatherContext(query) {
+    return (await this.contextFor(query)).text;
   }
-  /** Records a finished task's outcome — best-effort. */
+  /** 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}`,
@@ -2447,18 +2511,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 entry of entries) {
+      byScope.set(entry.scope, [...byScope.get(entry.scope) ?? [], entry]);
+    }
+    const parts = [];
+    for (const scope of ["project", "task", "role", "knowledge"]) {
+      const scopeEntries = byScope.get(scope) ?? [];
+      if (scopeEntries.length === 0) continue;
+      const lines = scopeEntries.map((entry) => {
+        const category = entry.category ? `[${entry.category}] ` : "";
+        return `- ${category}${entry.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 };
   }
 };
 
@@ -2470,7 +2569,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
   });
@@ -3298,6 +3401,91 @@ function buildPlanner(plannerConfig, chat, log = logger) {
 
 // src/reports/aggregate.ts
 import { randomBytes as randomBytes5 } from "crypto";
+
+// src/reports/schema.ts
+import { z as z3 } from "zod";
+var evidenceSchema = z3.union([
+  z3.string().transform((excerpt) => ({ kind: "observation", excerpt })),
+  z3.object({
+    kind: z3.enum(["file", "line", "url", "command", "observation", "artifact"]),
+    ref: z3.string().optional(),
+    line: z3.number().int().optional(),
+    excerpt: z3.string().optional(),
+    agent: z3.string().optional()
+  })
+]);
+var findingSchema = z3.object({
+  id: z3.string().min(1),
+  title: z3.string().min(1),
+  detail: z3.string().default(""),
+  description: z3.string().optional(),
+  severity: z3.enum(["info", "low", "medium", "high", "critical"]).optional(),
+  confidence: z3.enum(["low", "medium", "high"]).optional(),
+  evidence: z3.array(evidenceSchema).optional(),
+  location: z3.string().optional(),
+  tags: z3.array(z3.string()).optional(),
+  source: z3.object({ agent: z3.string().optional(), reportId: z3.string().optional(), pipelineRunId: z3.string().optional() }).optional(),
+  recommendation: z3.string().optional()
+});
+var artifactSchema = z3.object({
+  kind: z3.enum(["file", "patch", "log", "screenshot", "document", "data"]),
+  ref: z3.string().min(1),
+  description: z3.string().optional(),
+  mediaType: z3.string().optional(),
+  bytes: z3.number().int().optional()
+});
+var reportSchema = z3.object({
+  id: z3.string().min(1),
+  taskId: z3.string().min(1),
+  agent: z3.string().min(1),
+  agentId: z3.string().optional(),
+  pipelineRunId: z3.string().optional(),
+  model: z3.string().optional(),
+  summary: z3.string(),
+  findings: z3.array(findingSchema),
+  recommendations: z3.array(z3.string()),
+  confidence: z3.enum(["low", "medium", "high"]).optional(),
+  evidence: z3.array(evidenceSchema).optional(),
+  artifacts: z3.array(artifactSchema).optional(),
+  createdAt: z3.string().min(1),
+  metadata: z3.record(z3.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
+  );
+}
+function normalizeFinding(finding) {
+  return {
+    ...finding,
+    description: finding.description ?? finding.detail,
+    evidence: normalizeEvidence(finding.evidence)
+  };
+}
+
+// src/reports/aggregate.ts
 var SEVERITY_RANK2 = {
   info: 0,
   low: 1,
@@ -3344,7 +3532,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_RANK2[finding.severity] > SEVERITY_RANK2[group.severity])) {
       group.severity = finding.severity;
     }
@@ -3356,7 +3544,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) {
@@ -3438,6 +3626,7 @@ function extractReportFromText(raw, meta) {
     id: `${meta.taskId}-f-${index + 1}`,
     title: truncate3(text, 120),
     detail: text,
+    description: text,
     severity: guessSeverity(text)
   }));
   return {
@@ -3448,7 +3637,8 @@ function extractReportFromText(raw, meta) {
     summary,
     findings,
     recommendations: recommendationTexts.map((t) => truncate3(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()
   };
 }
@@ -3464,27 +3654,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) {
@@ -3552,7 +3761,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
   });
@@ -3590,7 +3803,7 @@ var ProjectStores = class {
 };
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.7";
+var OMNINODE_VERSION = "2.0.0-alpha.9";
 export {
   AgentAdapterRegistry,
   AgentError,
@@ -3607,6 +3820,7 @@ export {
   JsonFileStore,
   LocalMemoryProvider,
   Logger,
+  MAX_CONTEXT_CHARS,
   MAX_MESSAGE_BYTES,
   MemoryError,
   MemoryService,
@@ -3655,7 +3869,9 @@ export {
   createTaskEngine,
   decodeMessage,
   decodeStream,
+  defaultMetadata,
   defaultProjectConfigYaml,
+  defaultSearch,
   describeExit,
   encodeMessage,
   envelope,
@@ -3674,6 +3890,8 @@ export {
   loadConfig,
   logger,
   newMessageId,
+  normalizeEvidence,
+  normalizeFinding,
   parseHello,
   parsePlanJson,
   parseRetryAfter,
@@ -3693,6 +3911,7 @@ export {
   sanitizeChunk,
   similar,
   validateEnvelope,
+  validateReport,
   validateWorkingDirectory
 };
 //# sourceMappingURL=index.js.map