@agentfield/sdk 0.1.123 → 0.1.124-rc.2

package/README.md

@@ -7,6 +7,26 @@ The TypeScript SDK provides an idiomatic Node.js interface for building and runn
 npm install @agentfield/sdk
 ```
 
+## Memory event subscriptions
+
+Pass filters when starting a memory event client to apply them on the server before events are sent over the WebSocket:
+
+```ts
+import { MemoryEventClient } from '@agentfield/sdk';
+
+const events = new MemoryEventClient('http://localhost:8080');
+events.onEvent((event) => console.log(event.key));
+events.start({
+  patterns: ['user_*', 'session.*'],
+  scope: 'session',
+  scopeId: 'session-123'
+});
+```
+
+`patterns` is a list of memory-key globs and is sent as a comma-separated query parameter. `scope` accepts `workflow`, `session`, `actor`, or `global`, while `scopeId` maps to the server's `scope_id` parameter. All filters are optional, and automatic reconnects reuse the original filters. Omitting them keeps the existing behavior of receiving all events.
+
+Server-side filtering reduces WebSocket traffic and client-side processing for high-volume event streams.
+
 ## Rate limiting
 AI calls are wrapped with a stateless rate limiter that matches the Python SDK: exponential backoff, container-scoped jitter, Retry-After support, and a circuit breaker.
 

package/dist/index.d.ts

@@ -219,6 +219,12 @@ declare class MemoryClient extends MemoryClientBase {
 }
 
 type MemoryEventHandler = (event: MemoryChangeEvent) => Promise<void> | void;
+interface MemoryEventSubscriptionOptions {
+    /** Memory key glob patterns to filter on the server. */
+    patterns?: string[];
+    scope?: MemoryRequestOptions['scope'];
+    scopeId?: string;
+}
 interface MemoryEventHistoryOptions extends MemoryRequestOptions {
     patterns?: string[];
     since?: Date;
@@ -234,13 +240,16 @@ declare class MemoryEventClient extends MemoryClientBase {
     private reconnectTimer?;
     private readonly headers;
     private readonly apiKey?;
+    private subscriptionOptions;
     constructor(baseUrl: string, headers?: Record<string, string | number | boolean | undefined>, apiKey?: string);
-    start(): void;
+    /** Starts the event stream with optional server-side filters. */
+    start(options?: MemoryEventSubscriptionOptions): void;
     onEvent(handler: MemoryEventHandler): void;
     stop(): void;
     private cleanup;
     private connect;
     private scheduleReconnect;
+    private buildWebSocketUrl;
     private buildForwardHeaders;
     history(options?: MemoryEventHistoryOptions): Promise<MemoryChangeEvent[]>;
 }
@@ -3003,4 +3012,4 @@ declare function simulateSchedule<R>(handler: (ctx: SimulatedContext) => R | Pro
  */
 declare function loadFixture(source: string): Record<string, unknown>;
 
-export { ACTIVE_STATUSES, AIClient, type AIConfig, type AIEmbeddingOptions, type AIRequestOptions, type AIStream, type AIToolRequestOptions, Agent, type AgentCapability, type AgentConfig, type AgentHandler, AgentRouter, type AgentRouterOptions, type AgentState, ApprovalClient, type ApprovalDecision, type ApprovalRequestResponse, ApprovalResult, type ApprovalStatusResponse, Audio, type AudioOutput, type AudioRequest, type AuditTrailExport, type AuditTrailFilters, type Awaitable, CANONICAL_STATUSES, type CompactCapability, type CompactDiscoveryResponse, type CostEntry, type CostEntryInit, CostTracker, DIDAuthenticator, type DIDIdentity, type DIDIdentityPackage, type DIDRegistrationRequest, type DIDRegistrationResponse, type DeploymentType, DidClient, DidInterface, DidManager, type DidResolver, type DiscoveryFormat, type DiscoveryOptions, type DiscoveryPagination, type DiscoveryResponse, type DiscoveryResult, type EventTriggerBinding, type EventTriggerSpec, ExecutionContext, type ExecutionCredential, type ExecutionLogAttributes, type ExecutionLogBatchPayload, type ExecutionLogContext, type ExecutionLogEmitOptions, type ExecutionLogEntry, type ExecutionLogLevel, type ExecutionLogTransport, type ExecutionLogTransportPayload, type ExecutionLogWireEntry, ExecutionLogger, type ExecutionLoggerOptions, type ExecutionMetadata, ExecutionStatus, type ExecutionStatusValue, File, type FileOutput, type GenerateCredentialOptions, type GenerateCredentialParams, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, type HarnessConfig, type HarnessOptions, type HarnessProvider, type HarnessResult, HarnessRunner, type HealthStatus, Image, type ImageOutput, type ImageRequest, JWE_ALG, JWE_ENC, KEY_AGREEMENT_TYPE, MODEL_VARIANT_SEP, type MediaProvider, MediaProviderError, type MediaResponse, MediaRouter, type MemoryChangeEvent, MemoryClient, MemoryClientBase, type MemoryConfig, MemoryEventClient, type MemoryEventHandler, type MemoryEventHistoryOptions, MemoryInterface, type MemoryRequestMetadata, type MemoryRequestOptions, type MemoryScope, type MemoryWatchHandler, type Metrics, type ModelVariant, type MultimodalContent, MultimodalResponse, OpenRouterMediaProvider, type OpenRouterMediaProviderOptions, PauseClock, PauseManager, type Payload, PayloadEncryptionError, RateLimitError, type RateLimiterOptions, type RawExecutionContext, type RawResult, RealtimeSession, type ReasonerCapability, ReasonerContext, type ReasonerDefinition, type ReasonerHandler, type ReasonerOptions, type RequestApprovalPayload, SUPPORTED_PROVIDERS, SUPPORTED_SESSION_TRANSPORTS, type ScheduleTriggerBinding, type ScheduleTriggerSpec, type ServerlessAdapter, type ServerlessEvent, type ServerlessResponse, type SessionDefinition, type SessionOptions, type SessionProvider, type SessionTransport, type SessionTransportCapability, SessionTransportError, type SessionTurn, type SimulateScheduleOptions, type SimulateTriggerOptions, type SimulatedContext, type SkillCapability, SkillContext, type SkillDefinition, type SkillHandler, type SkillOptions, StatelessRateLimiter, TERMINAL_STATUSES, Text, type ToolCallConfig, type ToolCallRecord, type ToolCallTrace, type ToolsOption, type TriggerBinding, type TriggerContext, type TriggerEnvelope, USAGE_ENVELOPE_KEY, type UnwrapResult, type UsageEntryWire, type UsageSummaryWire, type VectorSearchOptions, type VectorSearchResult, Video, type VideoFrameImage, type VideoInputReference, type VideoRequest, type WaitForApprovalOptions, type WorkflowCredential, type WorkflowMetadata, type WorkflowProgressOptions, WorkflowReporter, type ZodSchema, applyTriggerTransform, attachUsageToSyncResult, audioFromBase64, audioFromBuffer, audioFromFile, audioFromUrl, buildProvider, buildSessionDefinition, buildToolConfig, capabilitiesToTools, capabilityToMetadataTool, capabilityToTool, createExecutionLogger, createHarnessResult, createMetrics, createMultimodalResponse, createRawResult, decrypt, decryptToString, deriveProvider, encryptForDid, encryptToJwk, eventTrigger, executeToolCallLoop, extractKeyAgreementJwk, fileFromBase64, fileFromBuffer, fileFromPath, fileFromUrl, generateX25519KeyPair, getCurrentContext, getCurrentSkillContext, imageFromBase64, imageFromBuffer, imageFromFile, imageFromUrl, installApprovalWebhookRoute, isActive, isExecutionLogBatchPayload, isTerminal, isTriggerEnvelope, loadFixture, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, resolveModelAndVariant, scheduleTrigger, serializeExecutionLogEntry, simulateSchedule, simulateTrigger, splitModelVariant, text, triggerToPayload, unwrapEnvelope, usageSummaryOrNull, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };
+export { ACTIVE_STATUSES, AIClient, type AIConfig, type AIEmbeddingOptions, type AIRequestOptions, type AIStream, type AIToolRequestOptions, Agent, type AgentCapability, type AgentConfig, type AgentHandler, AgentRouter, type AgentRouterOptions, type AgentState, ApprovalClient, type ApprovalDecision, type ApprovalRequestResponse, ApprovalResult, type ApprovalStatusResponse, Audio, type AudioOutput, type AudioRequest, type AuditTrailExport, type AuditTrailFilters, type Awaitable, CANONICAL_STATUSES, type CompactCapability, type CompactDiscoveryResponse, type CostEntry, type CostEntryInit, CostTracker, DIDAuthenticator, type DIDIdentity, type DIDIdentityPackage, type DIDRegistrationRequest, type DIDRegistrationResponse, type DeploymentType, DidClient, DidInterface, DidManager, type DidResolver, type DiscoveryFormat, type DiscoveryOptions, type DiscoveryPagination, type DiscoveryResponse, type DiscoveryResult, type EventTriggerBinding, type EventTriggerSpec, ExecutionContext, type ExecutionCredential, type ExecutionLogAttributes, type ExecutionLogBatchPayload, type ExecutionLogContext, type ExecutionLogEmitOptions, type ExecutionLogEntry, type ExecutionLogLevel, type ExecutionLogTransport, type ExecutionLogTransportPayload, type ExecutionLogWireEntry, ExecutionLogger, type ExecutionLoggerOptions, type ExecutionMetadata, ExecutionStatus, type ExecutionStatusValue, File, type FileOutput, type GenerateCredentialOptions, type GenerateCredentialParams, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, type HarnessConfig, type HarnessOptions, type HarnessProvider, type HarnessResult, HarnessRunner, type HealthStatus, Image, type ImageOutput, type ImageRequest, JWE_ALG, JWE_ENC, KEY_AGREEMENT_TYPE, MODEL_VARIANT_SEP, type MediaProvider, MediaProviderError, type MediaResponse, MediaRouter, type MemoryChangeEvent, MemoryClient, MemoryClientBase, type MemoryConfig, MemoryEventClient, type MemoryEventHandler, type MemoryEventHistoryOptions, type MemoryEventSubscriptionOptions, MemoryInterface, type MemoryRequestMetadata, type MemoryRequestOptions, type MemoryScope, type MemoryWatchHandler, type Metrics, type ModelVariant, type MultimodalContent, MultimodalResponse, OpenRouterMediaProvider, type OpenRouterMediaProviderOptions, PauseClock, PauseManager, type Payload, PayloadEncryptionError, RateLimitError, type RateLimiterOptions, type RawExecutionContext, type RawResult, RealtimeSession, type ReasonerCapability, ReasonerContext, type ReasonerDefinition, type ReasonerHandler, type ReasonerOptions, type RequestApprovalPayload, SUPPORTED_PROVIDERS, SUPPORTED_SESSION_TRANSPORTS, type ScheduleTriggerBinding, type ScheduleTriggerSpec, type ServerlessAdapter, type ServerlessEvent, type ServerlessResponse, type SessionDefinition, type SessionOptions, type SessionProvider, type SessionTransport, type SessionTransportCapability, SessionTransportError, type SessionTurn, type SimulateScheduleOptions, type SimulateTriggerOptions, type SimulatedContext, type SkillCapability, SkillContext, type SkillDefinition, type SkillHandler, type SkillOptions, StatelessRateLimiter, TERMINAL_STATUSES, Text, type ToolCallConfig, type ToolCallRecord, type ToolCallTrace, type ToolsOption, type TriggerBinding, type TriggerContext, type TriggerEnvelope, USAGE_ENVELOPE_KEY, type UnwrapResult, type UsageEntryWire, type UsageSummaryWire, type VectorSearchOptions, type VectorSearchResult, Video, type VideoFrameImage, type VideoInputReference, type VideoRequest, type WaitForApprovalOptions, type WorkflowCredential, type WorkflowMetadata, type WorkflowProgressOptions, WorkflowReporter, type ZodSchema, applyTriggerTransform, attachUsageToSyncResult, audioFromBase64, audioFromBuffer, audioFromFile, audioFromUrl, buildProvider, buildSessionDefinition, buildToolConfig, capabilitiesToTools, capabilityToMetadataTool, capabilityToTool, createExecutionLogger, createHarnessResult, createMetrics, createMultimodalResponse, createRawResult, decrypt, decryptToString, deriveProvider, encryptForDid, encryptToJwk, eventTrigger, executeToolCallLoop, extractKeyAgreementJwk, fileFromBase64, fileFromBuffer, fileFromPath, fileFromUrl, generateX25519KeyPair, getCurrentContext, getCurrentSkillContext, imageFromBase64, imageFromBuffer, imageFromFile, imageFromUrl, installApprovalWebhookRoute, isActive, isExecutionLogBatchPayload, isTerminal, isTriggerEnvelope, loadFixture, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, resolveModelAndVariant, scheduleTrigger, serializeExecutionLogEntry, simulateSchedule, simulateTrigger, splitModelVariant, text, triggerToPayload, unwrapEnvelope, usageSummaryOrNull, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };

package/dist/index.js

@@ -3888,14 +3888,20 @@ var MemoryEventClient = class extends MemoryClientBase {
   reconnectTimer;
   headers;
   apiKey;
+  subscriptionOptions = {};
   constructor(baseUrl, headers, apiKey) {
     super(baseUrl, headers);
     this.url = `${baseUrl.replace(/^http/, "ws")}/api/v1/memory/events/ws`;
     this.headers = this.buildForwardHeaders(headers ?? {});
     this.apiKey = apiKey;
   }
-  start() {
+  /** Starts the event stream with optional server-side filters. */
+  start(options = {}) {
     if (this.ws) return;
+    this.subscriptionOptions = {
+      ...options,
+      patterns: options.patterns ? [...options.patterns] : void 0
+    };
     this.connect();
   }
   onEvent(handler) {
@@ -3919,7 +3925,7 @@ var MemoryEventClient = class extends MemoryClientBase {
   connect() {
     this.cleanup();
     this.reconnectPending = false;
-    this.ws = new WebSocket(this.url, { headers: this.headers });
+    this.ws = new WebSocket(this.buildWebSocketUrl(), { headers: this.headers });
     this.ws.on("open", () => {
       this.reconnectDelay = 1e3;
     });
@@ -3947,6 +3953,21 @@ var MemoryEventClient = class extends MemoryClientBase {
       this.connect();
     }, this.reconnectDelay);
   }
+  buildWebSocketUrl() {
+    const params = new URLSearchParams();
+    const { patterns, scope, scopeId } = this.subscriptionOptions;
+    if (patterns && patterns.length > 0) {
+      params.set("patterns", patterns.join(","));
+    }
+    if (scope) {
+      params.set("scope", scope);
+    }
+    if (scopeId) {
+      params.set("scope_id", scopeId);
+    }
+    const query = params.toString();
+    return query ? `${this.url}?${query}` : this.url;
+  }
   buildForwardHeaders(headers) {
     const allowed = /* @__PURE__ */ new Set(["authorization", "cookie"]);
     const sanitized = {};