hebbrix 2.2.0 → 2.3.0

package/dist/index.mjs

@@ -34,7 +34,7 @@ function enforceSearchSafety(response, rowsKey = "results") {
       reason = "no_match_contains_evidence";
     }
   }
-  if (reason || data.degraded === true || data.no_match === true || data.abstain_recommended === true) {
+  if (reason || data.no_match === true) {
     data[rowsKey] = [];
     if (rowsKey === "results") data.total = 0;
     data.no_match = true;
@@ -46,10 +46,78 @@ function enforceSearchSafety(response, rowsKey = "results") {
       data.sdk_safety_reason = reason;
       data.grounding = { status: "no_grounded_match", reason };
     }
+  } else if (data.degraded === true || data.abstain_recommended === true) {
+    data.sdk_safety_reason = "degraded_evidence_preserved";
   }
   return data;
 }
 
+// src/errors.ts
+var HebbrixError = class _HebbrixError extends Error {
+  constructor(message, statusCode, options = {}) {
+    super(message);
+    this.name = "HebbrixError";
+    this.statusCode = statusCode;
+    this.code = options.code;
+    this.requestId = options.requestId;
+    this.details = options.details;
+    Object.setPrototypeOf(this, _HebbrixError.prototype);
+  }
+};
+var EntitlementError = class _EntitlementError extends HebbrixError {
+  constructor(message, statusCode, options = {}) {
+    super(message, statusCode, options);
+    this.name = "EntitlementError";
+    Object.setPrototypeOf(this, _EntitlementError.prototype);
+  }
+};
+var IndexingTimeoutError = class _IndexingTimeoutError extends Error {
+  constructor(message, receipt) {
+    super(message);
+    this.name = "IndexingTimeoutError";
+    this.receipt = { ...receipt };
+    this.memoryIds = [...receipt.memory_ids || []];
+    this.statusUrl = receipt.status_url;
+    Object.setPrototypeOf(this, _IndexingTimeoutError.prototype);
+  }
+};
+var AuthenticationError = class _AuthenticationError extends HebbrixError {
+  constructor(message = "Authentication failed", options = {}) {
+    super(message, 401, options);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, _AuthenticationError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends HebbrixError {
+  constructor(message, errors, options = {}) {
+    super(message, 422, options);
+    this.name = "ValidationError";
+    this.errors = errors;
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var NotFoundError = class _NotFoundError extends HebbrixError {
+  constructor(message = "Resource not found", options = {}) {
+    super(message, 404, options);
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, _NotFoundError.prototype);
+  }
+};
+var RateLimitError = class _RateLimitError extends HebbrixError {
+  constructor(message = "Rate limit exceeded", options = {}) {
+    super(message, 429, options);
+    this.name = "RateLimitError";
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+};
+var ServerError = class _ServerError extends HebbrixError {
+  constructor(message = "Internal server error", options = {}) {
+    super(message, 500, options);
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, _ServerError.prototype);
+  }
+};
+
 // src/resources.ts
 var BaseResource = class {
   constructor(client) {
@@ -144,6 +212,89 @@ var MemoriesResource = class extends BaseResource {
       })
     });
   }
+  /**
+   * Create up to 100 memories with one unambiguous readiness contract.
+   * `wait_for_index=true` resolves only for a fully searchable batch. A durable
+   * server-side 202 is polled to the caller's deadline; expiry raises a typed
+   * `IndexingTimeoutError` carrying the original durable receipt.
+   */
+  async createBatch(params) {
+    if (!params.memories?.length || params.memories.length > 100) {
+      throw new TypeError("memories must contain between 1 and 100 items");
+    }
+    if (params.memories.some((item) => !item.content?.trim())) {
+      throw new TypeError("every batch memory must contain non-empty content");
+    }
+    const {
+      idempotency_key,
+      signal,
+      index_timeout_ms,
+      index_poll_interval_ms,
+      ...body
+    } = params;
+    const receipt = await this.client.request(
+      "POST",
+      "/v1/memories/batch",
+      {
+        headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+        body: JSON.stringify({ wait_for_index: false, ...body }),
+        signal
+      }
+    );
+    if (params.wait_for_index && !receipt.searchable) {
+      return this.waitForBatchSearchable(receipt, {
+        timeoutMs: index_timeout_ms,
+        pollIntervalMs: index_poll_interval_ms,
+        signal
+      });
+    }
+    return receipt;
+  }
+  /** Poll every item in an asynchronous batch receipt until it is searchable. */
+  async waitForBatchSearchable(receipt, options = {}) {
+    const ids = [...new Set(receipt.memory_ids || [])];
+    if (!ids.length) {
+      throw new Error("batch receipt does not contain memory_ids");
+    }
+    const timeoutMs = Math.max(0, options.timeoutMs ?? 6e4);
+    const pollIntervalMs = Math.max(50, options.pollIntervalMs ?? 500);
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      if (options.signal?.aborted) {
+        throw options.signal.reason || new Error("batch readiness polling was aborted");
+      }
+      const rows = await Promise.all(ids.map((id) => this.get(id)));
+      const terminal = rows.find(
+        (row) => ["failed", "cancelled", "canceled"].includes(
+          String(row.processing_status || "").toLowerCase()
+        )
+      );
+      if (terminal) {
+        throw new Error(
+          `memory ${terminal.id} indexing reached terminal state ${terminal.processing_status}`
+        );
+      }
+      if (rows.every((row) => row.searchable === true)) {
+        return {
+          ...receipt,
+          processing_status: "completed",
+          searchable: true,
+          results: ids.map((id) => ({
+            id,
+            memory_id: id,
+            processing_status: "completed"
+          }))
+        };
+      }
+      if (Date.now() >= deadline) {
+        throw new IndexingTimeoutError(
+          `batch was not searchable within ${timeoutMs}ms; the write is durable`,
+          receipt
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+  }
   /**
    * List memories
    */
@@ -333,8 +484,7 @@ var RLResource = class extends BaseResource {
    * Train the Memory Manager agent using RL
    */
   async trainMemoryManager(params) {
-    return this.client.post("/rl/train/memory-manager", {
-      collection_id: params.collection_id,
+    return this.client.post("/v1/rl/train/memory-manager", {
       num_episodes: params.num_episodes || 100,
       ...params
     });
@@ -343,8 +493,7 @@ var RLResource = class extends BaseResource {
    * Train the Answer Agent using RL
    */
   async trainAnswerAgent(params) {
-    return this.client.post("/rl/train/answer-agent", {
-      collection_id: params.collection_id,
+    return this.client.post("/v1/rl/train/answer-agent", {
       num_episodes: params.num_episodes || 100,
       ...params
     });
@@ -353,69 +502,91 @@ var RLResource = class extends BaseResource {
    * Get RL training metrics
    */
   async getMetrics() {
-    return this.client.get("/rl/metrics");
+    return this.client.get("/v1/rl/metrics");
   }
   /**
    * Evaluate a trained RL agent
    */
   async evaluate(agentType, collectionId) {
-    return this.client.post("/rl/evaluate", {
+    return this.client.post("/v1/rl/evaluate", {
       agent_type: agentType,
       collection_id: collectionId
     });
   }
 };
 var ProceduralResource = class extends BaseResource {
+  unwrapProcedure(response) {
+    if (response?.procedure) return response.procedure;
+    if (response?.procedure_id && !response?.id) {
+      return { ...response, id: response.procedure_id };
+    }
+    return response;
+  }
   /**
    * Create a new procedure
    */
   async create(params) {
-    return this.client.post("/procedural", {
+    const response = await this.client.post("/v1/procedures", {
       name: params.name,
       description: params.description,
-      trigger_condition: params.trigger_condition,
-      action_sequence: params.action_sequence,
+      condition: { expression: params.trigger_condition },
+      action: { steps: params.action_sequence },
       collection_id: params.collection_id,
       category: params.category,
-      metadata: params.metadata || {}
+      parameters: params.metadata || {}
     });
+    return this.unwrapProcedure(response);
   }
   /**
    * List procedures
    */
   async list(params) {
-    return this.client.get("/procedural", {
+    const response = await this.client.get("/v1/procedures", {
       collection_id: params?.collection_id,
       category: params?.category,
       skip: params?.skip || 0,
       limit: params?.limit || 100
     });
+    return Array.isArray(response) ? response : response?.procedures || [];
   }
   /**
    * Get a specific procedure
    */
   async get(procedureId) {
-    return this.client.get(`/procedural/${procedureId}`);
+    const response = await this.client.get(`/v1/procedures/${procedureId}`);
+    return this.unwrapProcedure(response);
   }
   /**
    * Execute a procedure
    */
   async execute(procedureId, context) {
-    return this.client.post(`/procedural/${procedureId}/execute`, {
-      context: context || {}
+    const response = await this.client.post(`/v1/procedures/${procedureId}/execute`, {
+      input_state: context || {}
     });
+    return response?.execution_result || response;
   }
   /**
    * Update a procedure
    */
   async update(procedureId, params) {
-    return this.client.patch(`/procedural/${procedureId}`, params);
+    const body = {};
+    if (params.name !== void 0) body.name = params.name;
+    if (params.description !== void 0) body.description = params.description;
+    if (params.trigger_condition !== void 0) {
+      body.condition = { expression: params.trigger_condition };
+    }
+    if (params.action_sequence !== void 0) {
+      body.action = { steps: params.action_sequence };
+    }
+    if (params.metadata !== void 0) body.parameters = params.metadata;
+    const response = await this.client.patch(`/v1/procedures/${procedureId}`, body);
+    return this.unwrapProcedure(response);
   }
   /**
    * Delete a procedure
    */
   async delete(procedureId) {
-    await this.client.delete(`/procedural/${procedureId}`);
+    await this.client.delete(`/v1/procedures/${procedureId}`);
   }
 };
 var TemporalResource = class extends BaseResource {
@@ -423,12 +594,15 @@ var TemporalResource = class extends BaseResource {
    * Add a temporal fact to the knowledge graph
    */
   async addFact(params) {
-    return this.client.post("/temporal/facts", {
+    return this.client.post("/v1/temporal/facts", {
       subject: params.subject,
+      subject_type: params.subject_type || "ENTITY",
       predicate: params.predicate,
       object: params.object,
+      object_type: params.object_type || "ENTITY",
       valid_from: params.valid_from,
       valid_until: params.valid_until,
+      observed_at: params.observed_at,
       confidence: params.confidence || 1,
       source_memory_id: params.source_memory_id,
       metadata: params.metadata || {}
@@ -438,29 +612,79 @@ var TemporalResource = class extends BaseResource {
    * Query temporal facts
    */
   async queryFacts(params) {
-    return this.client.get("/temporal/facts", {
-      subject: params?.subject,
-      predicate: params?.predicate,
-      object: params?.object,
-      at_time: params?.at_time
+    if (!params.subject) {
+      throw new TypeError("subject is required by the temporal query contract");
+    }
+    let rows;
+    if (params.at_time) {
+      const response = await this.queryAtTime({
+        subject: params.subject,
+        predicate: params.predicate,
+        timestamp: params.at_time
+      });
+      rows = response.facts || [];
+    } else if (params.predicate) {
+      const response = await this.history(
+        params.subject,
+        params.predicate
+      );
+      rows = response.history || [];
+    } else {
+      throw new TypeError("predicate or at_time is required");
+    }
+    return params.object === void 0 ? rows : rows.filter((row) => row.object === params.object);
+  }
+  async queryAtTime(params) {
+    return this.client.post("/v1/temporal/facts/query-at-time", params);
+  }
+  async history(subject, predicate, limit = 50) {
+    return this.client.get("/v1/temporal/facts/history", {
+      subject,
+      predicate,
+      limit
+    });
+  }
+  async conflicts(subject, predicate) {
+    return this.client.get("/v1/temporal/facts/conflicts", {
+      subject,
+      predicate
+    });
+  }
+  async invalidate(subject, predicate, object) {
+    return this.client.post("/v1/temporal/facts/invalidate", {
+      subject,
+      predicate,
+      object
     });
   }
   /**
    * Query knowledge state at a specific point in time
    */
   async pointInTime(timestamp, entity) {
-    return this.client.post("/temporal/point-in-time", {
+    if (!entity) {
+      throw new TypeError("entity is required and maps to the canonical subject");
+    }
+    return this.queryAtTime({
       timestamp,
-      entity
+      subject: entity
     });
   }
+  /** Permanently delete a tenant-scoped temporal fact by stable ID. */
+  async deleteFact(factId) {
+    return this.client.delete(`/v1/temporal/facts/${factId}`);
+  }
 };
 var WorkingMemoryResource = class extends BaseResource {
+  constructor(client) {
+    super(client);
+    this.sessionId = `sdk-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+  }
   /**
    * Add item to working memory buffer
    */
   async add(params) {
-    return this.client.post("/working-memory", {
+    return this.client.post("/v1/working-memory/add", {
+      session_id: params.session_id || this.sessionId,
       role: params.role,
       content: params.content,
       metadata: params.metadata || {}
@@ -469,48 +693,40 @@ var WorkingMemoryResource = class extends BaseResource {
   /**
    * Get current working memory context
    */
-  async getContext() {
-    return this.client.get("/working-memory/context");
+  async getContext(sessionId = this.sessionId, includeCompressed = false) {
+    return this.client.get(`/v1/working-memory/context/${sessionId}`, {
+      include_compressed: includeCompressed
+    });
   }
   /**
    * Compress working memory buffer
    */
-  async compress() {
-    return this.client.post("/working-memory/compress");
+  async compress(sessionId = this.sessionId) {
+    return this.client.post(`/v1/working-memory/compress/${sessionId}`);
   }
   /**
    * Clear working memory buffer
    */
-  async clear() {
-    return this.client.delete("/working-memory");
+  async clear(sessionId = this.sessionId) {
+    return this.client.delete(`/v1/working-memory/clear/${sessionId}`);
   }
 };
 var ConsolidationResource = class extends BaseResource {
   /**
    * Trigger memory consolidation
    */
-  async consolidate(collectionId, threshold = 100) {
-    return this.client.post("/consolidation/consolidate", {
+  async consolidate(collectionId, lookbackDays = 7, utilityThreshold = 0.3) {
+    return this.client.post("/v1/consolidation/consolidate", {
       collection_id: collectionId,
-      threshold
+      lookback_days: lookbackDays,
+      utility_threshold: utilityThreshold
     });
   }
   /**
    * Get consolidation statistics
    */
   async getStats(collectionId) {
-    return this.client.get("/consolidation/stats", {
-      collection_id: collectionId
-    });
-  }
-  /**
-   * Archive old memories
-   */
-  async archive(collectionId, beforeDate) {
-    return this.client.post("/consolidation/archive", {
-      collection_id: collectionId,
-      before_date: beforeDate
-    });
+    return this.client.get(`/v1/consolidation/stats/${collectionId}`);
   }
 };
 var MemoryToolsResource = class extends BaseResource {
@@ -518,100 +734,38 @@ var MemoryToolsResource = class extends BaseResource {
    * Replace memory content
    */
   async replace(params) {
-    return this.client.post("/memory-tools/replace", {
+    return this.client.post("/v1/memory-tools/replace", {
       memory_id: params.memory_id,
+      old_content: params.old_content,
       new_content: params.new_content,
-      reason: params.reason
+      collection_id: params.collection_id
     });
   }
   /**
    * Insert new memory at position
    */
   async insert(params) {
-    return this.client.post("/memory-tools/insert", {
+    const metadata = { ...params.metadata || {} };
+    if (params.position !== void 0) metadata.requested_position = params.position;
+    if (params.reason !== void 0) metadata.reason = params.reason;
+    return this.client.post("/v1/memory-tools/insert", {
       collection_id: params.collection_id,
       content: params.content,
-      position: params.position,
-      reason: params.reason
+      importance: params.importance ?? 0.5,
+      metadata
     });
   }
   /**
    * Re-evaluate memory in light of new information
    */
-  async rethink(memoryId, query) {
-    return this.client.post("/memory-tools/rethink", {
+  async rethink(memoryId, collectionId) {
+    return this.client.post("/v1/memory-tools/rethink", {
       memory_id: memoryId,
-      query
-    });
-  }
-};
-var WorldModelResource = class extends BaseResource {
-  /**
-   * Simulate retrieval without actually retrieving
-   */
-  async imagineRetrieval(query, collectionId) {
-    return this.client.post("/world-model/imagine-retrieval", {
-      query,
-      collection_id: collectionId
-    });
-  }
-  /**
-   * Plan memory operations to achieve goal
-   */
-  async plan(goal, collectionId) {
-    return this.client.post("/world-model/plan", {
-      goal,
       collection_id: collectionId
     });
   }
 };
 
-// src/errors.ts
-var HebbrixError = class _HebbrixError extends Error {
-  constructor(message, statusCode) {
-    super(message);
-    this.name = "HebbrixError";
-    this.statusCode = statusCode;
-    Object.setPrototypeOf(this, _HebbrixError.prototype);
-  }
-};
-var AuthenticationError = class _AuthenticationError extends HebbrixError {
-  constructor(message = "Authentication failed") {
-    super(message, 401);
-    this.name = "AuthenticationError";
-    Object.setPrototypeOf(this, _AuthenticationError.prototype);
-  }
-};
-var ValidationError = class _ValidationError extends HebbrixError {
-  constructor(message, errors) {
-    super(message, 422);
-    this.name = "ValidationError";
-    this.errors = errors;
-    Object.setPrototypeOf(this, _ValidationError.prototype);
-  }
-};
-var NotFoundError = class _NotFoundError extends HebbrixError {
-  constructor(message = "Resource not found") {
-    super(message, 404);
-    this.name = "NotFoundError";
-    Object.setPrototypeOf(this, _NotFoundError.prototype);
-  }
-};
-var RateLimitError = class _RateLimitError extends HebbrixError {
-  constructor(message = "Rate limit exceeded") {
-    super(message, 429);
-    this.name = "RateLimitError";
-    Object.setPrototypeOf(this, _RateLimitError.prototype);
-  }
-};
-var ServerError = class _ServerError extends HebbrixError {
-  constructor(message = "Internal server error") {
-    super(message, 500);
-    this.name = "ServerError";
-    Object.setPrototypeOf(this, _ServerError.prototype);
-  }
-};
-
 // src/client.ts
 var MemoryClient = class {
   constructor(config = {}) {
@@ -631,13 +785,12 @@ var MemoryClient = class {
     this.workingMemory = new WorkingMemoryResource(this);
     this.consolidation = new ConsolidationResource(this);
     this.memoryTools = new MemoryToolsResource(this);
-    this.worldModel = new WorldModelResource(this);
     this.proofloop = new ProofLoopResource(this);
   }
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.2.0"
+      "User-Agent": "hebbrix-typescript/2.3.0"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -646,39 +799,58 @@ var MemoryClient = class {
   }
   handleError(response, data) {
     const statusCode = response.status;
-    const message = data?.error?.message || data?.detail || response.statusText;
+    const envelope = data?.error || data?.detail || {};
+    const nested = envelope?.message;
+    const details = nested && typeof nested === "object" ? nested : envelope;
+    const message = details?.message || (typeof nested === "string" ? nested : void 0) || response.statusText;
+    const code = details?.code || envelope?.code;
+    const requestId = details?.request_id || envelope?.request_id || response.headers.get("X-Request-ID") || void 0;
     if (statusCode === 401) {
-      throw new AuthenticationError(message);
+      throw new AuthenticationError(message, { code, requestId, details });
     } else if (statusCode === 404) {
-      throw new NotFoundError(message);
+      throw new NotFoundError(message, { code, requestId, details });
     } else if (statusCode === 422) {
       const errors = data?.error?.details || [];
-      throw new ValidationError(message, errors);
+      throw new ValidationError(message, errors, { code, requestId, details });
     } else if (statusCode === 429) {
-      throw new RateLimitError(message);
+      throw new RateLimitError(message, { code, requestId, details });
     } else if (statusCode >= 500) {
-      throw new ServerError(message);
+      throw new ServerError(message, { code, requestId, details });
+    } else if ((statusCode === 402 || statusCode === 403) && (String(code || "").includes("ENTITLEMENT") || ["feature_not_available", "tier_upgrade_required"].includes(details?.error))) {
+      throw new EntitlementError(message, statusCode, {
+        code,
+        requestId,
+        details
+      });
     } else {
-      throw new HebbrixError(message, statusCode);
+      throw new HebbrixError(message, statusCode, { code, requestId, details });
     }
   }
   async request(method, path, options = {}) {
     const url = `${this.baseUrl}${path}`;
+    const { headers: requestHeaders, signal: requestSignal, ...requestOptions } = options;
     const response = await fetch(url, {
+      ...requestOptions,
       method,
       headers: {
         ...this.getHeaders(),
-        ...options.headers || {}
+        ...requestHeaders || {}
       },
-      ...options,
-      signal: AbortSignal.timeout(this.timeout)
+      signal: requestSignal || AbortSignal.timeout(this.timeout)
     });
-    let data;
+    let data = void 0;
     const contentType = response.headers.get("content-type");
-    if (contentType?.includes("application/json")) {
-      data = await response.json();
-    } else {
-      data = await response.text();
+    const responseText = await response.text();
+    if (responseText) {
+      if (contentType?.includes("application/json")) {
+        try {
+          data = JSON.parse(responseText);
+        } catch {
+          data = { detail: responseText };
+        }
+      } else {
+        data = responseText;
+      }
     }
     if (!response.ok) {
       this.handleError(response, data);
@@ -732,7 +904,9 @@ export {
   CollectionsResource,
   ConsolidationResource,
   CorrectionsResource,
+  EntitlementError,
   HebbrixError,
+  IndexingTimeoutError,
   MemoriesResource,
   MemoryClient,
   MemoryJobsResource,
@@ -747,6 +921,5 @@ export {
   TemporalResource,
   ValidationError,
   WorkingMemoryResource,
-  WorldModelResource,
   enforceSearchSafety
 };