@komputer-ai/sdk 0.11.7 → 0.11.8

package/README.md

@@ -127,6 +127,23 @@ for await (const event of stream) {
 }
 ```
 
+#### Distributed consumers — `{ group }`
+
+By default, `watchAgent` opens a **broadcast** subscription: every connected client receives every event. If you run multiple instances of your service (e.g. 3 replicas of a Slack bot) and they all call `client.watchAgent("my-agent")` without further options, **each instance will process every event** — duplicate work.
+
+To get queue-style delivery (each event handled by exactly one instance across your fleet), pass `{ group }`:
+
+```ts
+const stream = await client.watchAgent("my-agent", { group: "my-bot" });
+```
+
+The API uses Redis-coordinated routing to deliver each event to exactly one client per group, regardless of how many replicas connect or which API replica they hit. Pick any string for the group name (`my-bot`, `audit-pipeline`, `prod-webhook-fwd`).
+
+**Use broadcast** for: dashboards, debugging, single-instance workers, anywhere "see everything" is the goal.
+**Use `{ group }`** for: distributed services, webhook forwarders, anywhere you'd otherwise dedupe events yourself.
+
+On write failure, the API retries delivery to other group members on the same replica before giving up — an event is only lost when all members on the routing replica fail simultaneously. Use `client.getAgentEvents({ name, limit: ... })` to backfill on reconnect if you need strict exactly-once guarantees.
+
 ### Direct API access
 
 For advanced use cases, the underlying generated API clients are available:

package/dist/client.d.ts

@@ -171,5 +171,17 @@ export declare class KomputerClient {
     listTemplates(): Promise<{
         [key: string]: any;
     }>;
-    watchAgent(name: string): Promise<AgentEventStream>;
+    /**
+     * Stream live agent events.
+     *
+     * @param name Agent name.
+     * @param options.group Optional consumer group name. When set, this watcher joins
+     *   a group and each event is delivered to exactly one client per group across all
+     *   API replicas — useful when running multiple SDK instances in a distributed system
+     *   that should not each process the same event. Without `group`, every connected
+     *   client receives every event (broadcast).
+     */
+    watchAgent(name: string, options?: {
+        group?: string;
+    }): Promise<AgentEventStream>;
 }

package/dist/client.js

@@ -268,7 +268,17 @@ class KomputerClient {
         });
     }
     // --- WebSocket ---
-    watchAgent(name) {
+    /**
+     * Stream live agent events.
+     *
+     * @param name Agent name.
+     * @param options.group Optional consumer group name. When set, this watcher joins
+     *   a group and each event is delivered to exactly one client per group across all
+     *   API replicas — useful when running multiple SDK instances in a distributed system
+     *   that should not each process the same event. Without `group`, every connected
+     *   client receives every event (broadcast).
+     */
+    watchAgent(name, options) {
         return __awaiter(this, void 0, void 0, function* () {
             const wsUrl = this._baseUrl.replace("http://", "ws://").replace("https://", "wss://");
             let history = [];
@@ -286,7 +296,7 @@ class KomputerClient {
             catch (_a) {
                 // History fetch failed — proceed with live-only.
             }
-            return new watch_1.AgentEventStream(wsUrl, name, history);
+            return new watch_1.AgentEventStream(wsUrl, name, history, options === null || options === void 0 ? void 0 : options.group);
         });
     }
 }

package/dist/esm/client.d.ts

@@ -171,5 +171,17 @@ export declare class KomputerClient {
     listTemplates(): Promise<{
         [key: string]: any;
     }>;
-    watchAgent(name: string): Promise<AgentEventStream>;
+    /**
+     * Stream live agent events.
+     *
+     * @param name Agent name.
+     * @param options.group Optional consumer group name. When set, this watcher joins
+     *   a group and each event is delivered to exactly one client per group across all
+     *   API replicas — useful when running multiple SDK instances in a distributed system
+     *   that should not each process the same event. Without `group`, every connected
+     *   client receives every event (broadcast).
+     */
+    watchAgent(name: string, options?: {
+        group?: string;
+    }): Promise<AgentEventStream>;
 }

package/dist/esm/client.js

@@ -265,7 +265,17 @@ export class KomputerClient {
         });
     }
     // --- WebSocket ---
-    watchAgent(name) {
+    /**
+     * Stream live agent events.
+     *
+     * @param name Agent name.
+     * @param options.group Optional consumer group name. When set, this watcher joins
+     *   a group and each event is delivered to exactly one client per group across all
+     *   API replicas — useful when running multiple SDK instances in a distributed system
+     *   that should not each process the same event. Without `group`, every connected
+     *   client receives every event (broadcast).
+     */
+    watchAgent(name, options) {
         return __awaiter(this, void 0, void 0, function* () {
             const wsUrl = this._baseUrl.replace("http://", "ws://").replace("https://", "wss://");
             let history = [];
@@ -283,7 +293,7 @@ export class KomputerClient {
             catch (_a) {
                 // History fetch failed — proceed with live-only.
             }
-            return new AgentEventStream(wsUrl, name, history);
+            return new AgentEventStream(wsUrl, name, history, options === null || options === void 0 ? void 0 : options.group);
         });
     }
 }

package/dist/esm/watch.d.ts

@@ -25,7 +25,7 @@ export declare class AgentEventStream implements AsyncIterable<AgentEvent> {
     private resolve;
     private done;
     private seen;
-    constructor(wsUrl: string, agentName: string, historyEvents?: AgentEvent[]);
+    constructor(wsUrl: string, agentName: string, historyEvents?: AgentEvent[], group?: string);
     private dedupKey;
     [Symbol.asyncIterator](): AsyncIterator<AgentEvent>;
     close(): void;

package/dist/esm/watch.js

@@ -13,7 +13,7 @@
  * }
  */
 export class AgentEventStream {
-    constructor(wsUrl, agentName, historyEvents) {
+    constructor(wsUrl, agentName, historyEvents, group) {
         this.queue = [];
         this.resolve = null;
         this.done = false;
@@ -27,7 +27,11 @@ export class AgentEventStream {
                 this.queue.push(e);
             }
         }
-        this.ws = new WebSocket(`${wsUrl}/api/v1/agents/${agentName}/ws`);
+        let endpoint = `${wsUrl}/api/v1/agents/${agentName}/ws`;
+        if (group) {
+            endpoint += `?group=${encodeURIComponent(group)}`;
+        }
+        this.ws = new WebSocket(endpoint);
         this.ws.onmessage = (event) => {
             const data = JSON.parse(event.data);
             const agentEvent = {

package/dist/watch.d.ts

@@ -25,7 +25,7 @@ export declare class AgentEventStream implements AsyncIterable<AgentEvent> {
     private resolve;
     private done;
     private seen;
-    constructor(wsUrl: string, agentName: string, historyEvents?: AgentEvent[]);
+    constructor(wsUrl: string, agentName: string, historyEvents?: AgentEvent[], group?: string);
     private dedupKey;
     [Symbol.asyncIterator](): AsyncIterator<AgentEvent>;
     close(): void;

package/dist/watch.js

@@ -16,7 +16,7 @@ exports.AgentEventStream = void 0;
  * }
  */
 class AgentEventStream {
-    constructor(wsUrl, agentName, historyEvents) {
+    constructor(wsUrl, agentName, historyEvents, group) {
         this.queue = [];
         this.resolve = null;
         this.done = false;
@@ -30,7 +30,11 @@ class AgentEventStream {
                 this.queue.push(e);
             }
         }
-        this.ws = new WebSocket(`${wsUrl}/api/v1/agents/${agentName}/ws`);
+        let endpoint = `${wsUrl}/api/v1/agents/${agentName}/ws`;
+        if (group) {
+            endpoint += `?group=${encodeURIComponent(group)}`;
+        }
+        this.ws = new WebSocket(endpoint);
         this.ws.onmessage = (event) => {
             const data = JSON.parse(event.data);
             const agentEvent = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@komputer-ai/sdk",
-  "version": "0.11.7",
+  "version": "0.11.8",
   "description": "TypeScript SDK for the komputer.ai platform",
   "author": "komputer-ai",
   "license": "MIT",