hebbrix 2.3.0 → 2.4.0

package/dist/index.js

@@ -27,7 +27,10 @@ __export(index_exports, {
   CorrectionsResource: () => CorrectionsResource,
   EntitlementError: () => EntitlementError,
   HebbrixError: () => HebbrixError,
+  IndexingAbortedError: () => IndexingAbortedError,
+  IndexingTerminalError: () => IndexingTerminalError,
   IndexingTimeoutError: () => IndexingTimeoutError,
+  IndexingWaitError: () => IndexingWaitError,
   MemoriesResource: () => MemoriesResource,
   MemoryClient: () => MemoryClient,
   MemoryJobsResource: () => MemoryJobsResource,
@@ -58,7 +61,7 @@ var REQUIRED_FIELDS = [
 function enforceSearchSafety(response, rowsKey = "results") {
   const data = { ...response };
   const rawRows = data[rowsKey];
-  const rows = Array.isArray(rawRows) ? rawRows.filter((row) => typeof row === "object" && row !== null) : [];
+  const rows = Array.isArray(rawRows) ? rawRows : [];
   const missing = REQUIRED_FIELDS.filter(
     (field) => !Object.prototype.hasOwnProperty.call(data, field)
   );
@@ -73,6 +76,22 @@ function enforceSearchSafety(response, rowsKey = "results") {
     reason = "invalid_grounding_receipt";
   } else if (!Array.isArray(data.evidence_ids)) {
     reason = "invalid_evidence_ids";
+  } else if (data.safety_contract_version !== "search-safety-v1") {
+    reason = "unsupported_safety_contract_version";
+  } else if (!Array.isArray(rawRows)) {
+    reason = "invalid_evidence_rows";
+  } else if (data.evidence_ids.some((id) => typeof id !== "string" || !id.trim())) {
+    reason = "invalid_evidence_ids";
+  } else if (new Set(data.evidence_ids).size !== data.evidence_ids.length) {
+    reason = "duplicate_evidence_ids";
+  } else if (rows.some((row) => {
+    if (!row || typeof row !== "object" || Array.isArray(row)) return true;
+    const id = "memory_id" in row ? row.memory_id : row.id;
+    return typeof id !== "string" || !id.trim() || "memory_id" in row && "id" in row && row.memory_id !== row.id;
+  })) {
+    reason = "invalid_evidence_row_identity";
+  } else if (rows.length === 0 && data.no_match === false) {
+    reason = "no_evidence_rows";
   } else {
     const evidenceIds = new Set(data.evidence_ids.map(String));
     const rowIds = rows.map((row) => row.memory_id ?? row.id).filter((value) => typeof value === "string" && value.length > 0);
@@ -90,6 +109,10 @@ function enforceSearchSafety(response, rowsKey = "results") {
     data.query_confidence = 0;
     data.evidence_ids = [];
     data.evidence_claims = [];
+    if (rowsKey === "sources") {
+      data.answer = null;
+      data.citations = [];
+    }
     if (reason) {
       data.sdk_safety_reason = reason;
       data.grounding = { status: "no_grounded_match", reason };
@@ -119,16 +142,72 @@ var EntitlementError = class _EntitlementError extends HebbrixError {
     Object.setPrototypeOf(this, _EntitlementError.prototype);
   }
 };
-var IndexingTimeoutError = class _IndexingTimeoutError extends Error {
-  constructor(message, receipt) {
+var IndexingWaitError = class _IndexingWaitError extends Error {
+  constructor(message, receipt, options = {}) {
     super(message);
-    this.name = "IndexingTimeoutError";
+    this.name = "IndexingWaitError";
     this.receipt = { ...receipt };
-    this.memoryIds = [...receipt.memory_ids || []];
-    this.statusUrl = receipt.status_url;
+    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);
@@ -242,22 +321,195 @@ 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();
+      }
     });
   }
   /**
@@ -478,7 +730,7 @@ var SearchResource = class extends BaseResource {
   }
 };
 var ProofLoopResource = class extends BaseResource {
-  /** Create a causal decision bound to search/chat evidence automatically. */
+  /** Record a recommendation; this never authorizes execution or proves causality. */
   async decide(params) {
     const context = params.proof_context;
     const token = typeof context === "string" ? context : context?.token;
@@ -497,6 +749,56 @@ var ProofLoopResource = class extends BaseResource {
   async getDecision(decisionId) {
     return this.client.get(`/v1/learning/decisions/${decisionId}`);
   }
+  /** Owner-session administration. Use a separate client for the verifier key. */
+  async registerVerifier(params) {
+    return this.client.post("/v1/learning/verifiers", params);
+  }
+  async revokeVerifier(verifierId) {
+    return this.client.post(
+      `/v1/learning/verifiers/${encodeURIComponent(verifierId)}/revoke`,
+      {}
+    );
+  }
+  async createEpisode(params) {
+    return this.client.post("/v1/learning/episodes", params);
+  }
+  async getEpisode(episodeId, offset = 0) {
+    return this.client.get(
+      `/v1/learning/episodes/${encodeURIComponent(episodeId)}`,
+      { offset }
+    );
+  }
+  async closeEpisode(episodeId, status) {
+    return this.client.post(
+      `/v1/learning/episodes/${encodeURIComponent(episodeId)}/close`,
+      { status }
+    );
+  }
+  /** Append an execution claim. This method does not execute a tool. */
+  async recordExecution(decisionId, claim) {
+    return this.client.post(
+      `/v1/learning/decisions/${encodeURIComponent(decisionId)}/executions`,
+      claim
+    );
+  }
+  async assessment(decisionId, evidenceOffset = 0) {
+    return this.client.get(
+      `/v1/learning/decisions/${encodeURIComponent(decisionId)}/assessment`,
+      { evidence_offset: evidenceOffset }
+    );
+  }
+  async verifierEvidence(verifierId, decisionId) {
+    return this.client.get(
+      `/v1/learning/verifiers/${encodeURIComponent(verifierId)}/decisions/${encodeURIComponent(decisionId)}`
+    );
+  }
+  /** Deliver using the dedicated source credential, after checking execution independently. */
+  async deliverVerifiedOutcomes(verifierId, delivery) {
+    return this.client.post(
+      `/v1/learning/verifiers/${encodeURIComponent(verifierId)}/events`,
+      delivery
+    );
+  }
   async defineMetric(params) {
     return this.client.post("/v1/learning/metrics", params);
   }
@@ -608,9 +910,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;
   }
   /**
@@ -627,7 +932,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);
   }
   /**
@@ -710,7 +1018,9 @@ var TemporalResource = class extends BaseResource {
    */
   async pointInTime(timestamp, entity) {
     if (!entity) {
-      throw new TypeError("entity is required and maps to the canonical subject");
+      throw new TypeError(
+        "entity is required and maps to the canonical subject"
+      );
     }
     return this.queryAtTime({
       timestamp,
@@ -794,7 +1104,8 @@ var MemoryToolsResource = class extends BaseResource {
    */
   async insert(params) {
     const metadata = { ...params.metadata || {} };
-    if (params.position !== void 0) metadata.requested_position = params.position;
+    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,
@@ -838,7 +1149,7 @@ var MemoryClient = class {
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.3.0"
+      "User-Agent": "hebbrix-typescript/2.4.0"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -864,7 +1175,9 @@ var MemoryClient = class {
       throw new RateLimitError(message, { code, requestId, details });
     } else if (statusCode >= 500) {
       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))) {
+    } 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,
@@ -876,7 +1189,11 @@ var MemoryClient = class {
   }
   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,
@@ -903,6 +1220,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) {
@@ -955,7 +1287,10 @@ var MemoryClient = class {
   CorrectionsResource,
   EntitlementError,
   HebbrixError,
+  IndexingAbortedError,
+  IndexingTerminalError,
   IndexingTimeoutError,
+  IndexingWaitError,
   MemoriesResource,
   MemoryClient,
   MemoryJobsResource,