hebbrix 2.2.1 → 2.3.1

package/dist/index.mjs

@@ -52,6 +52,128 @@ function enforceSearchSafety(response, rowsKey = "results") {
   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 IndexingWaitError = class _IndexingWaitError extends Error {
+  constructor(message, receipt, options = {}) {
+    super(message);
+    this.name = "IndexingWaitError";
+    this.receipt = { ...receipt };
+    this.memoryIds = [
+      ...new Set(
+        [
+          ...receipt.memory_ids || [],
+          receipt.memory_id,
+          receipt.id,
+          ...(receipt.results || []).map(
+            (row) => row.memory_id || row.id
+          )
+        ].filter(Boolean)
+      )
+    ];
+    this.jobId = receipt.job_id;
+    this.statusUrl = receipt.status_url || (this.memoryIds.length === 1 ? `/v1/memories/${encodeURIComponent(this.memoryIds[0])}` : this.jobId ? `/v1/memory-jobs/${encodeURIComponent(this.jobId)}` : void 0);
+    this.requestId = receipt.request_id;
+    this.outboxEventId = receipt.outbox_event_id;
+    this.indexingEventId = receipt.indexing_event_id || this.outboxEventId;
+    this.eventId = receipt.event_id || this.indexingEventId;
+    this.idempotencyReplay = receipt.idempotency_replay;
+    this.idempotencyKey = options.idempotencyKey || receipt.idempotency_key;
+    this.retryAfter = receipt.retry_after;
+    this.recovery = Object.fromEntries(
+      Object.entries({
+        memory_ids: this.memoryIds,
+        job_id: this.jobId,
+        status_url: this.statusUrl,
+        request_id: this.requestId,
+        outbox_event_id: this.outboxEventId,
+        indexing_event_id: this.indexingEventId,
+        event_id: this.eventId,
+        idempotency_key: this.idempotencyKey,
+        idempotency_replay: this.idempotencyReplay,
+        retry_after: this.retryAfter
+      }).filter(([, value]) => value !== void 0 && value !== null)
+    );
+    this.cause = options.cause;
+    Object.setPrototypeOf(this, _IndexingWaitError.prototype);
+  }
+};
+var IndexingTimeoutError = class _IndexingTimeoutError extends IndexingWaitError {
+  constructor(message, receipt, options = {}) {
+    super(message, receipt, options);
+    this.name = "IndexingTimeoutError";
+    Object.setPrototypeOf(this, _IndexingTimeoutError.prototype);
+  }
+};
+var IndexingAbortedError = class _IndexingAbortedError extends IndexingWaitError {
+  constructor(message, receipt, options = {}) {
+    super(message, receipt, options);
+    this.name = "IndexingAbortedError";
+    Object.setPrototypeOf(this, _IndexingAbortedError.prototype);
+  }
+};
+var IndexingTerminalError = class _IndexingTerminalError extends IndexingWaitError {
+  constructor(message, receipt, processingStatus, options = {}) {
+    super(message, receipt, options);
+    this.name = "IndexingTerminalError";
+    this.processingStatus = processingStatus;
+    Object.setPrototypeOf(this, _IndexingTerminalError.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) {
@@ -128,29 +250,202 @@ var CollectionsResource = class extends BaseResource {
 };
 var MemoriesResource = class extends BaseResource {
   /**
-   * Create a new memory
+   * Create one logical memory write. When `wait_for_index=true`, a durable
+   * pending receipt is polled without issuing a second create request.
    */
   async create(params) {
     if (!params.content?.trim() && !params.messages?.length) {
       throw new TypeError("content or messages must be provided");
     }
-    const { idempotency_key, ...input } = params;
-    return this.client.request("POST", "/v1/memories", {
-      headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
-      body: JSON.stringify({
-        source_type: "text",
-        metadata: {},
-        infer: false,
-        wait_for_index: false,
-        ...input
-      })
+    const {
+      idempotency_key,
+      signal,
+      index_timeout_ms,
+      index_poll_interval_ms,
+      ...input
+    } = params;
+    const receipt = await this.client.request(
+      "POST",
+      "/v1/memories",
+      {
+        headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+        body: JSON.stringify({
+          source_type: "text",
+          metadata: {},
+          infer: false,
+          wait_for_index: false,
+          ...input
+        }),
+        signal
+      }
+    );
+    if (params.wait_for_index && !this.isSearchableCompletion(receipt)) {
+      return this.waitForSearchable(receipt, {
+        timeoutMs: index_timeout_ms,
+        pollIntervalMs: index_poll_interval_ms,
+        signal,
+        idempotencyKey: idempotency_key
+      });
+    }
+    return receipt;
+  }
+  /** Poll a single-write durable receipt until every accepted memory is searchable. */
+  async waitForSearchable(receipt, options = {}) {
+    if (this.isSearchableCompletion(receipt)) {
+      return receipt;
+    }
+    if (this.isTerminalStatus(receipt.processing_status)) {
+      const status = String(receipt.processing_status).toLowerCase();
+      throw new IndexingTerminalError(
+        `memory indexing reached terminal state ${status}`,
+        receipt,
+        status,
+        { idempotencyKey: options.idempotencyKey }
+      );
+    }
+    const ids = this.memoryIds(receipt);
+    if (!ids.length) {
+      throw new Error("memory receipt does not contain a durable memory id");
+    }
+    const timeoutMs = Math.max(0, options.timeoutMs ?? 6e4);
+    const pollIntervalMs = Math.max(50, options.pollIntervalMs ?? 500);
+    const deadline = Date.now() + timeoutMs;
+    const paths = ids.map(
+      (id, index) => index === 0 && receipt.status_url ? this.readinessPath(receipt.status_url, id) : `/v1/memories/${encodeURIComponent(id)}`
+    );
+    while (true) {
+      this.throwIfPollingAborted(receipt, options);
+      if (Date.now() >= deadline) {
+        throw new IndexingTimeoutError(
+          `memory was not searchable within ${timeoutMs}ms; the write is durable`,
+          receipt,
+          { idempotencyKey: options.idempotencyKey }
+        );
+      }
+      let rows;
+      try {
+        rows = await Promise.all(
+          paths.map(
+            (path) => this.client.request("GET", path, {
+              signal: options.signal
+            })
+          )
+        );
+      } catch (error) {
+        if (options.signal?.aborted) {
+          throw new IndexingAbortedError(
+            "memory readiness polling was aborted after the write became durable",
+            receipt,
+            { idempotencyKey: options.idempotencyKey, cause: error }
+          );
+        }
+        throw error;
+      }
+      const terminal = rows.find(
+        (row) => this.isTerminalStatus(row.processing_status)
+      );
+      if (terminal) {
+        const status = String(terminal.processing_status).toLowerCase();
+        throw new IndexingTerminalError(
+          `memory ${terminal.id} indexing reached terminal state ${status}`,
+          receipt,
+          status,
+          { idempotencyKey: options.idempotencyKey }
+        );
+      }
+      if (rows.every(
+        (row) => row.searchable === true && String(row.processing_status || "").toLowerCase() === "completed"
+      )) {
+        return {
+          ...receipt,
+          processing_status: "completed",
+          searchable: true,
+          results: receipt.results.map((result) => ({
+            ...result,
+            processing_status: "completed"
+          }))
+        };
+      }
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        continue;
+      }
+      await this.pollingDelay(
+        Math.min(pollIntervalMs, remainingMs),
+        receipt,
+        options
+      );
+    }
+  }
+  memoryIds(receipt) {
+    return [
+      ...new Set(
+        (receipt.results || []).map((row) => row.memory_id || row.id).filter((id) => Boolean(id))
+      )
+    ];
+  }
+  isSearchableCompletion(receipt) {
+    return receipt.searchable === true && String(receipt.processing_status || "").toLowerCase() === "completed";
+  }
+  isTerminalStatus(status) {
+    return ["failed", "cancelled", "canceled"].includes(
+      String(status || "").toLowerCase()
+    );
+  }
+  readinessPath(statusUrl, memoryId) {
+    try {
+      const parsed = new URL(statusUrl, "https://status.hebbrix.invalid");
+      if (!["http:", "https:"].includes(parsed.protocol)) {
+        return `/v1/memories/${encodeURIComponent(memoryId)}`;
+      }
+      return `${parsed.pathname}${parsed.search}`;
+    } catch {
+      return `/v1/memories/${encodeURIComponent(memoryId)}`;
+    }
+  }
+  throwIfPollingAborted(receipt, options) {
+    if (options.signal?.aborted) {
+      throw new IndexingAbortedError(
+        "memory readiness polling was aborted after the write became durable",
+        receipt,
+        {
+          idempotencyKey: options.idempotencyKey,
+          cause: options.signal.reason
+        }
+      );
+    }
+  }
+  async pollingDelay(delayMs, receipt, options) {
+    await new Promise((resolve, reject) => {
+      const onAbort = () => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        reject(
+          new IndexingAbortedError(
+            "memory readiness polling was aborted after the write became durable",
+            receipt,
+            {
+              idempotencyKey: options.idempotencyKey,
+              cause: options.signal?.reason
+            }
+          )
+        );
+      };
+      const timer = setTimeout(() => {
+        options.signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, delayMs);
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      if (options.signal?.aborted) {
+        onAbort();
+      }
     });
   }
   /**
    * Create up to 100 memories with one unambiguous readiness contract.
-   * `wait_for_index=true` resolves only for a fully searchable batch; a server
-   * deadline or indexing failure rejects the request instead of returning a
-   * successful processing receipt.
+   * `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) {
@@ -159,7 +454,13 @@ var MemoriesResource = class extends BaseResource {
     if (params.memories.some((item) => !item.content?.trim())) {
       throw new TypeError("every batch memory must contain non-empty content");
     }
-    const { idempotency_key, signal, ...body } = params;
+    const {
+      idempotency_key,
+      signal,
+      index_timeout_ms,
+      index_poll_interval_ms,
+      ...body
+    } = params;
     const receipt = await this.client.request(
       "POST",
       "/v1/memories/batch",
@@ -169,10 +470,12 @@ var MemoriesResource = class extends BaseResource {
         signal
       }
     );
-    if (params.wait_for_index && !(receipt.searchable === true && receipt.processing_status === "completed")) {
-      throw new Error(
-        "wait_for_index batch response was not fully searchable; retry with the same Idempotency-Key"
-      );
+    if (params.wait_for_index && !receipt.searchable) {
+      return this.waitForBatchSearchable(receipt, {
+        timeoutMs: index_timeout_ms,
+        pollIntervalMs: index_poll_interval_ms,
+        signal
+      });
     }
     return receipt;
   }
@@ -213,7 +516,10 @@ var MemoriesResource = class extends BaseResource {
         };
       }
       if (Date.now() >= deadline) {
-        throw new Error(`batch was not searchable within ${timeoutMs}ms`);
+        throw new IndexingTimeoutError(
+          `batch was not searchable within ${timeoutMs}ms; the write is durable`,
+          receipt
+        );
       }
       await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
     }
@@ -407,8 +713,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
     });
@@ -417,8 +722,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
     });
@@ -427,13 +731,13 @@ 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
     });
@@ -485,9 +789,12 @@ var ProceduralResource = class extends BaseResource {
    * Execute a procedure
    */
   async execute(procedureId, context) {
-    const response = await this.client.post(`/v1/procedures/${procedureId}/execute`, {
-      input_state: context || {}
-    });
+    const response = await this.client.post(
+      `/v1/procedures/${procedureId}/execute`,
+      {
+        input_state: context || {}
+      }
+    );
     return response?.execution_result || response;
   }
   /**
@@ -504,7 +811,10 @@ var ProceduralResource = class extends BaseResource {
       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);
+    const response = await this.client.patch(
+      `/v1/procedures/${procedureId}`,
+      body
+    );
     return this.unwrapProcedure(response);
   }
   /**
@@ -519,12 +829,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 || {}
@@ -534,33 +847,81 @@ 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(`/temporal/facts/${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 || {}
@@ -569,48 +930,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 {
@@ -618,100 +971,39 @@ 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 = {}) {
@@ -731,13 +1023,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.1"
+      "User-Agent": "hebbrix-typescript/2.3.1"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -746,26 +1037,42 @@ var MemoryClient = class {
   }
   handleError(response, data) {
     const statusCode = response.status;
-    const detail = data?.detail;
-    const message = data?.error?.message || (typeof detail === "string" ? detail : detail?.message) || 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 {
+      headers: requestHeaders,
+      signal: requestSignal,
+      ...requestOptions
+    } = options;
     const response = await fetch(url, {
       ...requestOptions,
       method,
@@ -792,6 +1099,21 @@ var MemoryClient = class {
     if (!response.ok) {
       this.handleError(response, data);
     }
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      const requestId = response.headers.get("X-Request-ID");
+      const statusUrl = response.headers.get("Location");
+      const outboxEventId = response.headers.get("X-Hebbrix-Index-Event");
+      const retryAfter = response.headers.get("Retry-After");
+      const idempotencyReplay = response.headers.get("X-Idempotent-Replay");
+      data = {
+        ...data,
+        ...data.request_id === void 0 && requestId ? { request_id: requestId } : {},
+        ...data.status_url === void 0 && statusUrl ? { status_url: statusUrl } : {},
+        ...data.outbox_event_id === void 0 && outboxEventId ? { outbox_event_id: outboxEventId } : {},
+        ...data.retry_after === void 0 && retryAfter ? { retry_after: retryAfter } : {},
+        ...data.idempotency_replay === void 0 && idempotencyReplay ? { idempotency_replay: idempotencyReplay.toLowerCase() === "true" } : {}
+      };
+    }
     return data;
   }
   async get(path, params) {
@@ -841,7 +1163,12 @@ export {
   CollectionsResource,
   ConsolidationResource,
   CorrectionsResource,
+  EntitlementError,
   HebbrixError,
+  IndexingAbortedError,
+  IndexingTerminalError,
+  IndexingTimeoutError,
+  IndexingWaitError,
   MemoriesResource,
   MemoryClient,
   MemoryJobsResource,
@@ -856,6 +1183,5 @@ export {
   TemporalResource,
   ValidationError,
   WorkingMemoryResource,
-  WorldModelResource,
   enforceSearchSafety
 };