@granular-software/sdk 0.4.16 → 0.4.17

package/dist/index.d.mts

@@ -359,7 +359,7 @@ interface BuildListResponse {
 }
 interface SemanticVersionDiffEntry {
     operationId: string;
-    kind: 'create' | 'update' | 'relationship' | 'effect' | 'unknown';
+    kind: 'create' | 'update' | 'relationship' | 'effect' | 'eventStream' | 'unknown';
     changeType: 'added' | 'removed' | 'changed';
     label: string;
     additive: boolean;
@@ -1024,6 +1024,22 @@ interface ManifestEffectDeclaration {
     tags?: string[];
     metamodels?: ManifestEffectMetamodelSpec;
 }
+/**
+ * An event type within an event stream definition
+ */
+interface ManifestEventTypeDef {
+    name: string;
+    description?: string;
+    payloadSchema: ManifestEffectSchema;
+}
+/**
+ * Event stream definition for outgoing typed events
+ */
+interface ManifestEventStreamDef {
+    name: string;
+    description?: string;
+    eventTypes: ManifestEventTypeDef[];
+}
 /**
  * A single operation in a manifest volume
  */
@@ -1046,6 +1062,8 @@ interface ManifestOperation {
     defineRelationship?: ManifestRelationshipDef;
     /** Declare a build-owned effect */
     withEffect?: ManifestEffectDeclaration;
+    /** Define an outgoing event stream with typed events */
+    defineEventStream?: ManifestEventStreamDef;
 }
 /**
  * A volume in a manifest
@@ -1098,6 +1116,29 @@ interface APIError {
 interface DeleteResponse {
     deleted: boolean;
 }
+interface StreamEvent {
+    eventId: string;
+    streamName: string;
+    eventType: string;
+    payload: Record<string, unknown>;
+    environmentId: string;
+    sessionId?: string;
+    subjectId?: string;
+    source: 'sandbox' | 'api';
+    isAcked: boolean;
+    createdAt: number;
+}
+interface StreamSubscription {
+    unsubscribe(): void;
+}
+interface StreamStats {
+    streamName: string;
+    eventType: string;
+    total: number;
+    last1h: number;
+    last24h: number;
+    unacked: number;
+}
 
 declare class WSClient {
     private ws;
@@ -1593,6 +1634,8 @@ declare class Environment extends Session {
     private _ensureWorkspaceToolsRoot;
     private _storeEffectSchemas;
     private _applyEffectMetamodels;
+    private _ensureWorkspaceStreamsRoot;
+    private _applyEventStreamDeclaration;
     private _applyEffectDeclaration;
     /**
      * Apply a single manifest operation via GraphQL
@@ -1887,6 +1930,40 @@ declare class Granular {
         create: (sandboxId: string, data: CreateEnvironmentData) => Promise<EnvironmentData>;
         delete: (environmentId: string) => Promise<DeleteResponse>;
     };
+    /**
+     * Event stream operations: query, subscribe, and acknowledge stream events
+     */
+    get streams(): {
+        getEvents: (params: {
+            ontology: string;
+            stream: string;
+            environment?: string;
+            session?: string;
+            eventTypes?: string[];
+            since?: Date;
+            until?: Date;
+            isAcked?: boolean;
+            limit?: number;
+            offset?: number;
+        }) => Promise<StreamEvent[]>;
+        subscribe: (params: {
+            ontology: string;
+            stream: string;
+            environment?: string;
+            session?: string;
+            eventTypes?: string[];
+            since?: Date;
+            onEvent: (event: StreamEvent) => void;
+            onError?: (err: Error) => void;
+            pollIntervalMs?: number;
+        }) => StreamSubscription;
+        ack: (eventId: string) => Promise<void>;
+        ackBatch: (eventIds: string[]) => Promise<void>;
+        getStats: (params: {
+            ontology: string;
+            environment?: string;
+        }) => Promise<StreamStats[]>;
+    };
     /**
      * Subject management
      */
@@ -1905,6 +1982,7 @@ declare class Granular {
         }) => Promise<Subject>;
         get: (id: string) => Promise<Subject>;
     };
+    private _resolveSandboxId;
     /**
      * Make an authenticated API request
      */
@@ -1920,4 +1998,4 @@ type EffectRuntimeRequest = {
 declare function normalizeEffectBehaviors(value?: ManifestEffectMetamodelSpec | ResolvedEffectBehaviors | null): ResolvedEffectBehaviors;
 declare function invokeRegisteredEffect(effectMap: Map<string, ToolWithHandler>, request: EffectRuntimeRequest): Promise<unknown>;
 
-export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type ConversationSessionInfo, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, type SemanticVersionDiff, type SemanticVersionDiffEntry, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, type Version, type VersionTag, type VersionTracking, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type ConversationSessionInfo, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestEventStreamDef, type ManifestEventTypeDef, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, type SemanticVersionDiff, type SemanticVersionDiffEntry, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type StreamEvent, type StreamStats, type StreamSubscription, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, type Version, type VersionTag, type VersionTracking, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };

package/dist/index.d.ts

@@ -359,7 +359,7 @@ interface BuildListResponse {
 }
 interface SemanticVersionDiffEntry {
     operationId: string;
-    kind: 'create' | 'update' | 'relationship' | 'effect' | 'unknown';
+    kind: 'create' | 'update' | 'relationship' | 'effect' | 'eventStream' | 'unknown';
     changeType: 'added' | 'removed' | 'changed';
     label: string;
     additive: boolean;
@@ -1024,6 +1024,22 @@ interface ManifestEffectDeclaration {
     tags?: string[];
     metamodels?: ManifestEffectMetamodelSpec;
 }
+/**
+ * An event type within an event stream definition
+ */
+interface ManifestEventTypeDef {
+    name: string;
+    description?: string;
+    payloadSchema: ManifestEffectSchema;
+}
+/**
+ * Event stream definition for outgoing typed events
+ */
+interface ManifestEventStreamDef {
+    name: string;
+    description?: string;
+    eventTypes: ManifestEventTypeDef[];
+}
 /**
  * A single operation in a manifest volume
  */
@@ -1046,6 +1062,8 @@ interface ManifestOperation {
     defineRelationship?: ManifestRelationshipDef;
     /** Declare a build-owned effect */
     withEffect?: ManifestEffectDeclaration;
+    /** Define an outgoing event stream with typed events */
+    defineEventStream?: ManifestEventStreamDef;
 }
 /**
  * A volume in a manifest
@@ -1098,6 +1116,29 @@ interface APIError {
 interface DeleteResponse {
     deleted: boolean;
 }
+interface StreamEvent {
+    eventId: string;
+    streamName: string;
+    eventType: string;
+    payload: Record<string, unknown>;
+    environmentId: string;
+    sessionId?: string;
+    subjectId?: string;
+    source: 'sandbox' | 'api';
+    isAcked: boolean;
+    createdAt: number;
+}
+interface StreamSubscription {
+    unsubscribe(): void;
+}
+interface StreamStats {
+    streamName: string;
+    eventType: string;
+    total: number;
+    last1h: number;
+    last24h: number;
+    unacked: number;
+}
 
 declare class WSClient {
     private ws;
@@ -1593,6 +1634,8 @@ declare class Environment extends Session {
     private _ensureWorkspaceToolsRoot;
     private _storeEffectSchemas;
     private _applyEffectMetamodels;
+    private _ensureWorkspaceStreamsRoot;
+    private _applyEventStreamDeclaration;
     private _applyEffectDeclaration;
     /**
      * Apply a single manifest operation via GraphQL
@@ -1887,6 +1930,40 @@ declare class Granular {
         create: (sandboxId: string, data: CreateEnvironmentData) => Promise<EnvironmentData>;
         delete: (environmentId: string) => Promise<DeleteResponse>;
     };
+    /**
+     * Event stream operations: query, subscribe, and acknowledge stream events
+     */
+    get streams(): {
+        getEvents: (params: {
+            ontology: string;
+            stream: string;
+            environment?: string;
+            session?: string;
+            eventTypes?: string[];
+            since?: Date;
+            until?: Date;
+            isAcked?: boolean;
+            limit?: number;
+            offset?: number;
+        }) => Promise<StreamEvent[]>;
+        subscribe: (params: {
+            ontology: string;
+            stream: string;
+            environment?: string;
+            session?: string;
+            eventTypes?: string[];
+            since?: Date;
+            onEvent: (event: StreamEvent) => void;
+            onError?: (err: Error) => void;
+            pollIntervalMs?: number;
+        }) => StreamSubscription;
+        ack: (eventId: string) => Promise<void>;
+        ackBatch: (eventIds: string[]) => Promise<void>;
+        getStats: (params: {
+            ontology: string;
+            environment?: string;
+        }) => Promise<StreamStats[]>;
+    };
     /**
      * Subject management
      */
@@ -1905,6 +1982,7 @@ declare class Granular {
         }) => Promise<Subject>;
         get: (id: string) => Promise<Subject>;
     };
+    private _resolveSandboxId;
     /**
      * Make an authenticated API request
      */
@@ -1920,4 +1998,4 @@ type EffectRuntimeRequest = {
 declare function normalizeEffectBehaviors(value?: ManifestEffectMetamodelSpec | ResolvedEffectBehaviors | null): ResolvedEffectBehaviors;
 declare function invokeRegisteredEffect(effectMap: Map<string, ToolWithHandler>, request: EffectRuntimeRequest): Promise<unknown>;
 
-export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type ConversationSessionInfo, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, type SemanticVersionDiff, type SemanticVersionDiffEntry, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, type Version, type VersionTag, type VersionTracking, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type ConversationSessionInfo, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestEventStreamDef, type ManifestEventTypeDef, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, type SemanticVersionDiff, type SemanticVersionDiffEntry, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type StreamEvent, type StreamStats, type StreamSubscription, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, type Version, type VersionTag, type VersionTracking, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };

package/dist/index.js

@@ -11837,6 +11837,70 @@ var Environment = class extends Session {
       await this._runGraphql(mutation.query, mutation.label);
     }
   }
+  async _ensureWorkspaceStreamsRoot() {
+    await this._runGraphql(
+      `mutation { create_model(path: "workspace", label: "workspace") { model { path } } }`,
+      "ensure workspace"
+    ).catch((error) => {
+      if (!error.message.includes("already exists")) throw error;
+    });
+    await this._runGraphql(
+      `mutation { at(path: "workspace") { create_submodel(subpath: "streams", label: "Streams") { model { path } } } }`,
+      "ensure workspace:streams"
+    ).catch((error) => {
+      if (!error.message.includes("already exists")) throw error;
+    });
+  }
+  async _applyEventStreamDeclaration(stream) {
+    await this._ensureWorkspaceStreamsRoot();
+    const streamPath = `workspace:streams:${stream.name}`;
+    await this._runGraphql(
+      `mutation { at(path: "workspace:streams") { create_submodel(subpath: ${JSON.stringify(stream.name)}, label: ${JSON.stringify(stream.name)}) { model { path } } } }`,
+      `create stream ${stream.name}`
+    ).catch((error) => {
+      if (!error.message.includes("already exists")) throw error;
+    });
+    if (stream.description) {
+      await this._runGraphql(
+        `mutation { at(path: ${JSON.stringify(streamPath)}) { set_description(description: ${JSON.stringify(stream.description)}) { done } } }`,
+        `set stream description on ${streamPath}`
+      );
+    }
+    for (const eventType of stream.eventTypes) {
+      const typePath = `${streamPath}:${eventType.name}`;
+      await this._runGraphql(
+        `mutation { at(path: ${JSON.stringify(streamPath)}) { create_submodel(subpath: ${JSON.stringify(eventType.name)}, label: ${JSON.stringify(eventType.name)}) { model { path } } } }`,
+        `create event type ${eventType.name} on ${streamPath}`
+      ).catch((error) => {
+        if (!error.message.includes("already exists")) throw error;
+      });
+      if (eventType.description) {
+        await this._runGraphql(
+          `mutation { at(path: ${JSON.stringify(typePath)}) { set_description(description: ${JSON.stringify(eventType.description)}) { done } } }`,
+          `set event type description on ${typePath}`
+        );
+      }
+      if (eventType.payloadSchema?.properties) {
+        const fieldSpecs = {};
+        for (const [propName, propSchema] of Object.entries(eventType.payloadSchema.properties)) {
+          const schema = propSchema;
+          fieldSpecs[propName] = {
+            type: schema.type ?? "string",
+            description: schema.description
+          };
+        }
+        await this._applyFields(typePath, fieldSpecs);
+      }
+      if (eventType.payloadSchema?.required?.length) {
+        await this._runGraphql(
+          `mutation { at(path: ${JSON.stringify(typePath)}) { create_submodel(subpath: "required", label: "required") { set_string_value(value: ${JSON.stringify(JSON.stringify(eventType.payloadSchema.required))}) { done } } } }`,
+          `store required fields on ${typePath}`
+        ).catch((error) => {
+          if (!error.message.includes("already exists")) throw error;
+        });
+      }
+    }
+  }
   async _applyEffectDeclaration(effect, aliasMap) {
     let containerPath = "workspace:tools:declared";
     if (effect.attachedClass) {
@@ -11924,6 +11988,9 @@ var Environment = class extends Session {
     if (op.withEffect) {
       await this._applyEffectDeclaration(op.withEffect, aliasMap);
     }
+    if (op.defineEventStream) {
+      await this._applyEventStreamDeclaration(op.defineEventStream);
+    }
   }
   /**
    * Apply field definitions (has) to a model via GraphQL
@@ -12896,6 +12963,107 @@ var Granular = class _Granular {
       }
     };
   }
+  /**
+   * Event stream operations: query, subscribe, and acknowledge stream events
+   */
+  get streams() {
+    return {
+      getEvents: async (params) => {
+        const sandbox = await this._resolveSandboxId(params.ontology);
+        const query = new URLSearchParams({ sandboxId: sandbox });
+        if (params.environment) query.set("environmentId", params.environment);
+        if (params.session) query.set("sessionId", params.session);
+        if (params.stream) query.set("streamName", params.stream);
+        if (params.eventTypes && params.eventTypes.length > 0) {
+          query.set("eventTypes", params.eventTypes.join(","));
+        }
+        if (params.since) query.set("since", params.since.toISOString());
+        if (params.until) query.set("until", params.until.toISOString());
+        if (params.isAcked !== void 0) query.set("isAcked", params.isAcked ? "1" : "0");
+        if (params.limit) query.set("limit", String(params.limit));
+        if (params.offset) query.set("offset", String(params.offset));
+        const result = await this.request(`/control/stream-events?${query.toString()}`);
+        return (result.items || []).map((row) => ({
+          eventId: row.event_id,
+          streamName: row.stream_name,
+          eventType: row.event_type,
+          payload: typeof row.payload === "string" ? JSON.parse(row.payload) : row.payload,
+          environmentId: row.environment_id,
+          sessionId: row.session_id,
+          subjectId: row.subject_id,
+          source: row.source,
+          isAcked: Boolean(row.is_acked),
+          createdAt: row.created_at
+        }));
+      },
+      subscribe: (params) => {
+        const interval = params.pollIntervalMs ?? 5e3;
+        let cursor = params.since || /* @__PURE__ */ new Date();
+        let running = true;
+        const seenEventIds = /* @__PURE__ */ new Set();
+        const poll = async () => {
+          while (running) {
+            try {
+              const events = await this.streams.getEvents({
+                ontology: params.ontology,
+                stream: params.stream,
+                environment: params.environment,
+                session: params.session,
+                eventTypes: params.eventTypes,
+                since: cursor,
+                limit: 100
+              });
+              const orderedEvents = [...events].sort((a, b) => a.createdAt - b.createdAt);
+              for (const event of orderedEvents) {
+                if (seenEventIds.has(event.eventId)) {
+                  continue;
+                }
+                seenEventIds.add(event.eventId);
+                const eventTime = new Date(event.createdAt * 1e3);
+                if (eventTime > cursor) {
+                  cursor = eventTime;
+                }
+                params.onEvent(event);
+              }
+            } catch (err) {
+              params.onError?.(err instanceof Error ? err : new Error(String(err)));
+            }
+            await new Promise((resolve) => setTimeout(resolve, interval));
+          }
+        };
+        poll();
+        return { unsubscribe: () => {
+          running = false;
+        } };
+      },
+      ack: async (eventId) => {
+        await this.request("/control/stream-events/ack", {
+          method: "POST",
+          body: JSON.stringify({ eventIds: [eventId] })
+        });
+      },
+      ackBatch: async (eventIds) => {
+        await this.request("/control/stream-events/ack", {
+          method: "POST",
+          body: JSON.stringify({ eventIds })
+        });
+      },
+      getStats: async (params) => {
+        const sandbox = await this._resolveSandboxId(params.ontology);
+        const query = new URLSearchParams({ sandboxId: sandbox });
+        if (params.environment) query.set("environmentId", params.environment);
+        const result = await this.request(`/control/stream-events/stats?${query.toString()}`);
+        return (result.items || []).map((row) => ({
+          streamName: row.stream_name,
+          eventType: row.event_type,
+          total: Number(row.total),
+          last1h: Number(row.last_1h),
+          last24h: Number(row.last_24h),
+          unacked: Number(row.unacked)
+        }));
+      }
+    };
+  }
   /**
    * Subject management
    */
@@ -12929,6 +13097,12 @@ var Granular = class _Granular {
       }
     };
   }
+  async _resolveSandboxId(ontologyNameOrId) {
+    if (ontologyNameOrId.startsWith("sbx_")) return ontologyNameOrId;
+    const result = await this.request(`/control/sandboxes?name=${encodeURIComponent(ontologyNameOrId)}`);
+    if (result.items.length === 0) throw new Error(`Ontology not found: ${ontologyNameOrId}`);
+    return result.items[0].sandboxId;
+  }
   /**
    * Make an authenticated API request
    */