hebbrix 2.2.1 → 2.3.1

package/dist/index.d.ts

@@ -38,6 +38,12 @@ interface Memory {
     source_reference?: string;
     access_count: number;
     last_accessed_at?: string;
+    /** Authoritative indexing state returned by GET /v1/memories/{id}. */
+    processing_status?: string;
+    /** True only when the memory is available to search. */
+    searchable?: boolean;
+    outbox_event_id?: string;
+    status_url?: string;
     created_at: string;
     updated_at: string;
 }
@@ -155,6 +161,12 @@ interface CreateMemoryParams {
     source?: string;
     /** Stable retry key sent as the Idempotency-Key transport header. */
     idempotency_key?: string;
+    /** Optional caller cancellation signal; it is never serialized. */
+    signal?: AbortSignal;
+    /** Client-side readiness deadline used only when wait_for_index=true. */
+    index_timeout_ms?: number;
+    /** Poll interval for a durable pending receipt. */
+    index_poll_interval_ms?: number;
 }
 interface MemoryAddResult {
     id: string;
@@ -162,6 +174,7 @@ interface MemoryAddResult {
     event: "ADD" | "UPDATE" | "NOOP" | string;
     memory?: string;
     reason?: string;
+    processing_status?: string;
 }
 interface MemoryAddResponse {
     results: MemoryAddResult[];
@@ -170,6 +183,9 @@ interface MemoryAddResponse {
     searchable: boolean;
     outbox_event_id?: string;
     status_url?: string;
+    idempotency_replay?: boolean;
+    request_id?: string;
+    retry_after?: string;
     job_id?: string;
     created_count: number;
     updated_count: number;
@@ -198,10 +214,16 @@ interface BatchMemoryCreateParams {
     idempotency_key?: string;
     /** Optional caller cancellation signal; it is never serialized. */
     signal?: AbortSignal;
+    /** Client-side readiness deadline used only when wait_for_index=true. */
+    index_timeout_ms?: number;
+    /** Poll interval for a durable 202 receipt. */
+    index_poll_interval_ms?: number;
 }
 interface BatchMemoryResponse {
     created: number;
     failed: number;
+    accepted: boolean;
+    durable: boolean;
     memory_ids: string[];
     errors: string[];
     results: Array<{
@@ -213,6 +235,8 @@ interface BatchMemoryResponse {
     searchable: boolean;
     outbox_event_id?: string;
     status_url?: string;
+    idempotency_replay?: boolean;
+    request_id?: string;
 }
 interface UpdateMemoryParams {
     content?: string;
@@ -246,8 +270,10 @@ interface ReasonParams {
     facets?: string[];
 }
 interface ListParams {
-    skip?: number;
+    cursor?: string;
     limit?: number;
+    name?: string;
+    name_prefix?: string;
 }
 interface MemoryListParams {
     collection_id?: string;
@@ -344,7 +370,7 @@ declare class CollectionsResource extends BaseResource {
     /**
      * List all collections
      */
-    list(params?: ListParams): Promise<Collection[]>;
+    list(params?: ListParams): Promise<CursorPage<Collection>>;
     /**
      * Get a specific collection
      */
@@ -360,14 +386,28 @@ declare class CollectionsResource extends BaseResource {
 }
 declare class MemoriesResource 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.
      */
     create(params: CreateMemoryParams): Promise<MemoryAddResponse>;
+    /** Poll a single-write durable receipt until every accepted memory is searchable. */
+    waitForSearchable(receipt: MemoryAddResponse, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+        signal?: AbortSignal;
+        idempotencyKey?: string;
+    }): Promise<MemoryAddResponse>;
+    private memoryIds;
+    private isSearchableCompletion;
+    private isTerminalStatus;
+    private readinessPath;
+    private throwIfPollingAborted;
+    private pollingDelay;
     /**
      * 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.
      */
     createBatch(params: BatchMemoryCreateParams): Promise<BatchMemoryResponse>;
     /** Poll every item in an asynchronous batch receipt until it is searchable. */
@@ -459,7 +499,6 @@ declare class RLResource extends BaseResource {
      * Train the Memory Manager agent using RL
      */
     trainMemoryManager(params: {
-        collection_id?: string;
         num_episodes?: number;
         [key: string]: any;
     }): Promise<any>;
@@ -467,7 +506,6 @@ declare class RLResource extends BaseResource {
      * Train the Answer Agent using RL
      */
     trainAnswerAgent(params: {
-        collection_id?: string;
         num_episodes?: number;
         [key: string]: any;
     }): Promise<any>;
@@ -534,8 +572,11 @@ declare class TemporalResource extends BaseResource {
         subject: string;
         predicate: string;
         object: string;
-        valid_from?: string;
+        valid_from: string;
         valid_until?: string;
+        observed_at?: string;
+        subject_type?: string;
+        object_type?: string;
         confidence?: number;
         source_memory_id?: string;
         metadata?: Record<string, any>;
@@ -543,12 +584,20 @@ declare class TemporalResource extends BaseResource {
     /**
      * Query temporal facts
      */
-    queryFacts(params?: {
+    queryFacts(params: {
         subject?: string;
         predicate?: string;
         object?: string;
         at_time?: string;
     }): Promise<any[]>;
+    queryAtTime(params: {
+        subject: string;
+        timestamp: string;
+        predicate?: string;
+    }): Promise<any>;
+    history(subject: string, predicate: string, limit?: number): Promise<any>;
+    conflicts(subject: string, predicate: string): Promise<any>;
+    invalidate(subject: string, predicate: string, object: string): Promise<any>;
     /**
      * Query knowledge state at a specific point in time
      */
@@ -557,6 +606,8 @@ declare class TemporalResource extends BaseResource {
     deleteFact(factId: string): Promise<any>;
 }
 declare class WorkingMemoryResource extends BaseResource {
+    readonly sessionId: string;
+    constructor(client: MemoryClient);
     /**
      * Add item to working memory buffer
      */
@@ -564,33 +615,30 @@ declare class WorkingMemoryResource extends BaseResource {
         role: string;
         content: string;
         metadata?: Record<string, any>;
+        session_id?: string;
     }): Promise<any>;
     /**
      * Get current working memory context
      */
-    getContext(): Promise<any>;
+    getContext(sessionId?: string, includeCompressed?: boolean): Promise<any>;
     /**
      * Compress working memory buffer
      */
-    compress(): Promise<any>;
+    compress(sessionId?: string): Promise<any>;
     /**
      * Clear working memory buffer
      */
-    clear(): Promise<any>;
+    clear(sessionId?: string): Promise<any>;
 }
 declare class ConsolidationResource extends BaseResource {
     /**
      * Trigger memory consolidation
      */
-    consolidate(collectionId: string, threshold?: number): Promise<any>;
+    consolidate(collectionId: string, lookbackDays?: number, utilityThreshold?: number): Promise<any>;
     /**
      * Get consolidation statistics
      */
     getStats(collectionId: string): Promise<any>;
-    /**
-     * Archive old memories
-     */
-    archive(collectionId: string, beforeDate?: string): Promise<any>;
 }
 declare class MemoryToolsResource extends BaseResource {
     /**
@@ -598,7 +646,9 @@ declare class MemoryToolsResource extends BaseResource {
      */
     replace(params: {
         memory_id: string;
+        old_content: string;
         new_content: string;
+        collection_id: string;
         reason?: string;
     }): Promise<any>;
     /**
@@ -607,23 +657,15 @@ declare class MemoryToolsResource extends BaseResource {
     insert(params: {
         collection_id: string;
         content: string;
-        position: number;
+        position?: number;
         reason?: string;
+        importance?: number;
+        metadata?: Record<string, any>;
     }): Promise<any>;
     /**
      * Re-evaluate memory in light of new information
      */
-    rethink(memoryId: string, query: string): Promise<any>;
-}
-declare class WorldModelResource extends BaseResource {
-    /**
-     * Simulate retrieval without actually retrieving
-     */
-    imagineRetrieval(query: string, collectionId?: string): Promise<any>;
-    /**
-     * Plan memory operations to achieve goal
-     */
-    plan(goal: string, collectionId?: string): Promise<any>;
+    rethink(memoryId: string, collectionId: string): Promise<any>;
 }
 
 declare class MemoryClient {
@@ -642,7 +684,6 @@ declare class MemoryClient {
     workingMemory: WorkingMemoryResource;
     consolidation: ConsolidationResource;
     memoryTools: MemoryToolsResource;
-    worldModel: WorldModelResource;
     proofloop: ProofLoopResource;
     constructor(config?: ClientConfig);
     private getHeaders;
@@ -662,23 +703,88 @@ declare class MemoryClient {
  */
 declare class HebbrixError extends Error {
     statusCode?: number;
-    constructor(message: string, statusCode?: number);
+    code?: string;
+    requestId?: string;
+    details?: Record<string, any>;
+    constructor(message: string, statusCode?: number, options?: {
+        code?: string;
+        requestId?: string;
+        details?: Record<string, any>;
+    });
+}
+declare class EntitlementError extends HebbrixError {
+    constructor(message: string, statusCode: number, options?: {
+        code?: string;
+        requestId?: string;
+        details?: Record<string, any>;
+    });
+}
+interface IndexingWaitErrorOptions {
+    idempotencyKey?: string;
+    cause?: unknown;
+}
+/** Base class for readiness failures after the API has accepted a durable write. */
+declare class IndexingWaitError extends Error {
+    receipt: Record<string, any>;
+    memoryIds: string[];
+    jobId?: string;
+    statusUrl?: string;
+    requestId?: string;
+    outboxEventId?: string;
+    indexingEventId?: string;
+    eventId?: string;
+    idempotencyReplay?: boolean;
+    idempotencyKey?: string;
+    retryAfter?: string;
+    recovery: Record<string, unknown>;
+    cause?: unknown;
+    constructor(message: string, receipt: Record<string, any>, options?: IndexingWaitErrorOptions);
+}
+declare class IndexingTimeoutError extends IndexingWaitError {
+    constructor(message: string, receipt: Record<string, any>, options?: IndexingWaitErrorOptions);
+}
+declare class IndexingAbortedError extends IndexingWaitError {
+    constructor(message: string, receipt: Record<string, any>, options?: IndexingWaitErrorOptions);
+}
+declare class IndexingTerminalError extends IndexingWaitError {
+    processingStatus: string;
+    constructor(message: string, receipt: Record<string, any>, processingStatus: string, options?: IndexingWaitErrorOptions);
 }
 declare class AuthenticationError extends HebbrixError {
-    constructor(message?: string);
+    constructor(message?: string, options?: {
+        code?: string;
+        requestId?: string;
+        details?: Record<string, any>;
+    });
 }
 declare class ValidationError extends HebbrixError {
     errors?: any[];
-    constructor(message: string, errors?: any[]);
+    constructor(message: string, errors?: any[], options?: {
+        code?: string;
+        requestId?: string;
+        details?: Record<string, any>;
+    });
 }
 declare class NotFoundError extends HebbrixError {
-    constructor(message?: string);
+    constructor(message?: string, options?: {
+        code?: string;
+        requestId?: string;
+        details?: Record<string, any>;
+    });
 }
 declare class RateLimitError extends HebbrixError {
-    constructor(message?: string);
+    constructor(message?: string, options?: {
+        code?: string;
+        requestId?: string;
+        details?: Record<string, any>;
+    });
 }
 declare class ServerError extends HebbrixError {
-    constructor(message?: string);
+    constructor(message?: string, options?: {
+        code?: string;
+        requestId?: string;
+        details?: Record<string, any>;
+    });
 }
 
 interface SafetyEnvelope {
@@ -701,4 +807,4 @@ interface SafetyEnvelope {
  */
 declare function enforceSearchSafety<T extends object>(response: T, rowsKey?: "results" | "sources"): T & SafetyEnvelope;
 
-export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type BatchMemoryCreateParams, type BatchMemoryItemParams, type BatchMemoryResponse, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CorrectionCreateParams, type CorrectionSearchParams, CorrectionsResource, type CreateCollectionParams, type CreateMemoryParams, type CursorPage, type EvidenceClaim, type GroundingReceipt, HebbrixError, type ListParams, MemoriesResource, type Memory, type MemoryAddResponse, type MemoryAddResult, MemoryClient, type MemoryJobReceipt, MemoryJobsResource, type MemoryListParams, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, type ProofLoopMetricParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SafetyEnvelope, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, WorldModelResource, enforceSearchSafety };
+export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type BatchMemoryCreateParams, type BatchMemoryItemParams, type BatchMemoryResponse, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CorrectionCreateParams, type CorrectionSearchParams, CorrectionsResource, type CreateCollectionParams, type CreateMemoryParams, type CursorPage, EntitlementError, type EvidenceClaim, type GroundingReceipt, HebbrixError, IndexingAbortedError, IndexingTerminalError, IndexingTimeoutError, IndexingWaitError, type IndexingWaitErrorOptions, type ListParams, MemoriesResource, type Memory, type MemoryAddResponse, type MemoryAddResult, MemoryClient, type MemoryJobReceipt, MemoryJobsResource, type MemoryListParams, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, type ProofLoopMetricParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SafetyEnvelope, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, enforceSearchSafety };