@blocks-network/sdk 0.1.45

package/dist/runtime/task-session.d.ts

@@ -0,0 +1,224 @@
+/**
+ * TaskSession - Consumer-side task session with eager subscription.
+ *
+ * Replaces SendMessageResult. Owns one task's channel subscription,
+ * parsed task events, discovered streams, and cleanup. Auto-closes
+ * on terminal event.
+ */
+import PubNub from 'pubnub';
+import { StreamClient, type StreamClientFromDescriptorOptions } from '../stream/index.js';
+import { StreamRef } from './stream-ref.js';
+import { type RpcClientConfig } from './rpc-client.js';
+import { type ArtifactRef, type DownloadedArtifact } from './artifacts.js';
+export type Unsubscribe = () => void;
+export declare const TERMINAL_STATES: Set<string>;
+export interface TaskEvent {
+    type: string;
+    taskId: string;
+    [key: string]: unknown;
+}
+export interface ProgressEvent {
+    type: 'progress';
+    taskId: string;
+    message?: string;
+    progress?: number;
+    streamEvent?: string;
+    [key: string]: unknown;
+}
+export interface ArtifactEvent {
+    type: 'artifact';
+    taskId: string;
+    artifactRef: ArtifactRef;
+    outputId?: string;
+    [key: string]: unknown;
+}
+export interface TerminalEvent {
+    type: 'terminal';
+    taskId: string;
+    state: 'completed' | 'failed' | 'canceled';
+    reason?: string;
+    error?: string;
+    [key: string]: unknown;
+}
+export interface CallbackErrorContext {
+    entryPoint: 'taskSession' | 'subscribeToTask';
+    callbackType: 'onProgress' | 'onArtifact' | 'onTerminal' | 'onSystem' | 'onEvent' | 'onStream' | 'streamPredicate';
+    event: TaskEvent | StreamRef;
+}
+export declare class TaskSession {
+    readonly taskId: string;
+    readonly ownerId: string;
+    readonly orgId: string;
+    readonly readToken: string | null;
+    readonly statusChannel: string;
+    private readonly pubnub;
+    private readonly ownsSubscribeClient;
+    private readonly sdkOptions;
+    private readonly agentName;
+    private readonly rpcConfig;
+    private readonly subscribeKey;
+    private readonly publishKey;
+    private progressCallbacks;
+    private artifactCallbacks;
+    private terminalCallbacks;
+    private eventCallbacks;
+    private streamCallbacks;
+    private errorCallbacks;
+    private streams;
+    private artifacts;
+    private streamWaiters;
+    private terminalWaiters;
+    private closed;
+    private listener;
+    private readonly autoDrain;
+    private terminalReceived;
+    private drainTimer;
+    private readonly drainWindowMs;
+    private openStreamClients;
+    private readonly seenTimetokens;
+    private static readonly SEEN_TIMETOKENS_MAX;
+    /** RPC response metadata from sendMessage(). */
+    readonly idempotent?: boolean;
+    readonly queued?: boolean;
+    readonly pushConfigId?: string;
+    /**
+     * Current session state. Set from history at construction time (for
+     * pre-closed idempotent hits and connect() sessions) and kept current
+     * on live `terminal` events. Treat as a live observable rather than an
+     * immutable snapshot: `StreamRef.open()` consults this value via its
+     * `sessionState` hook to short-circuit on terminal sessions.
+     */
+    state?: string;
+    /** Whether this is a skipSubscription session (terminal connect). */
+    private readonly skipSubscriptionMode;
+    constructor(opts: {
+        taskId: string;
+        ownerId: string;
+        orgId?: string;
+        readToken: string | null;
+        statusChannel?: string;
+        agentName: string;
+        pubnub: PubNub | null;
+        ownsSubscribeClient?: boolean;
+        sdkOptions: StreamClientFromDescriptorOptions;
+        rpcConfig?: RpcClientConfig;
+        idempotent?: boolean;
+        queued?: boolean;
+        pushConfigId?: string;
+        autoDrain?: boolean;
+        /**
+         * Duration in milliseconds the session waits for already-open streams
+         * to finish draining naturally after a terminal event. Defaults to
+         * 30000 ms (30 seconds). Ignored when `autoDrain` is false.
+         *
+         * Only applies to streams that were opened while the task was still
+         * active. Unopened streams on a terminal session throw
+         * `StreamUnavailableError` per the merged t7c baseline.
+         */
+        drainWindowMs?: number;
+        /**
+         * When true, the session starts already closed. Used for terminal
+         * idempotent hits where the task is already in a terminal state and
+         * no PubNub subscription is needed.
+         */
+        preClosed?: boolean;
+        /** The terminal state of the task (e.g., "completed", "failed", "canceled"). */
+        state?: string;
+        /** Skip PubNub subscription but keep client alive for downloadArtifact().
+         *  Used by connect() for terminal tasks. */
+        skipSubscription?: boolean;
+        /** Pre-populated stream refs from history (connect()). */
+        preloadedStreams?: Map<string, StreamRef>;
+        /** Pre-populated artifact refs from history (connect()). */
+        preloadedArtifacts?: ArtifactRef[];
+        /** External subscription managed by connect() for active tasks. */
+        externalSubscription?: {
+            listener: unknown;
+            channel: string;
+            onReady: (dispatch: (event: TaskEvent, timetoken?: string) => void) => void;
+        };
+    });
+    private setupSubscription;
+    private routeCallbackError;
+    private handleEvent;
+    /** Register a stream client for auto-drain tracking. */
+    private trackStreamClient;
+    private accumulateArtifact;
+    private handleStreamStarted;
+    private startAutoDrain;
+    /**
+     * Find a stream by runtime stream ID or declared stream key (Fix 12).
+     * Checks the map key first (runtime ID), then falls back to scanning
+     * descriptors for a matching declaredStream.
+     */
+    private findStreamByIdOrDeclared;
+    private resolveWaiters;
+    onProgress(cb: (event: ProgressEvent) => void): Unsubscribe;
+    onArtifact(cb: (event: ArtifactEvent) => void): Unsubscribe;
+    onTerminal(cb: (event: TerminalEvent) => void): Unsubscribe;
+    onEvent(cb: (event: TaskEvent) => void): Unsubscribe;
+    /**
+     * Register an error handler for callback exceptions.
+     * If registered, callback errors are routed here instead of console.warn.
+     * Returns an unsubscribe function.
+     */
+    onError(cb: (error: Error, context: CallbackErrorContext) => void): Unsubscribe;
+    /** Return all artifact refs seen so far (from history and live events). */
+    listArtifacts(): ArtifactRef[];
+    /**
+     * Download an artifact from an ArtifactRef.
+     * Delegates to the standalone downloadArtifact() helper.
+     * If the session has no active PubNub client (e.g., pre-closed or skipSubscription
+     * with destroyed client), lazily creates a temporary client for the download.
+     */
+    downloadArtifact(ref: ArtifactRef): Promise<DownloadedArtifact>;
+    onStream(cb: (stream: StreamRef) => void): Unsubscribe;
+    listStreams(): StreamRef[];
+    /**
+     * Open every readable stream known to this session synchronously.
+     *
+     * Returns an array of `StreamClient`s in insertion order (matching
+     * `listStreams()`). Outbound-only streams are skipped; streams that
+     * fail to open (already ended, terminal session, etc.) are skipped
+     * silently. Calling twice returns the same client objects for
+     * already-opened streams via `StreamRef.open()` idempotence.
+     *
+     * This is an active-session convenience. Under the merged t7c
+     * baseline, `StreamRef.open()` throws `StreamUnavailableError` for
+     * never-opened streams on a terminal session — call this method
+     * while the task is still running if the goal is to observe every
+     * stream.
+     */
+    openAllStreams(options?: {
+        reorderTimeoutMs?: number;
+    }): StreamClient[];
+    waitForStream(streamId?: string): Promise<StreamRef>;
+    waitForStreamWhere(predicate: (stream: StreamRef) => boolean): Promise<StreamRef>;
+    /**
+     * Wait for the task to reach a terminal state. Returns the terminal event.
+     *
+     * Resolves immediately if the session is already in a terminal state
+     * (pre-closed idempotent hit or terminal connect()).
+     *
+     * @param timeoutMs Optional timeout in milliseconds. Rejects with Error on timeout.
+     */
+    waitForTerminal(timeoutMs?: number): Promise<TerminalEvent>;
+    /**
+     * Download all accumulated artifacts and save them to a directory.
+     * Creates the directory if it does not exist.
+     * Returns the list of file paths written.
+     */
+    saveArtifacts(dir: string): Promise<string[]>;
+    cancel(): Promise<void>;
+    terminate(): Promise<void>;
+    close(): void;
+    /**
+     * Async close that awaits all StreamClient.end() calls before
+     * performing sync cleanup. Preferred over close() when streams
+     * may have buffered data to flush.
+     */
+    asyncClose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Whether the session has been closed. */
+    get isClosed(): boolean;
+}

package/dist/runtime/task-session.js

@@ -0,0 +1 @@
+import t from"pubnub";import{invertDirection as e}from"../stream/index.js";import{StreamRef as s}from"./stream-ref.js";import{taskChannel as r}from"./channel-manager.js";import{callRpc as i}from"./rpc-client.js";import{downloadArtifact as a}from"./artifacts.js";export const TERMINAL_STATES=new Set(["completed","failed","canceled"]);export class TaskSession{constructor(t){if(this.progressCallbacks=[],this.artifactCallbacks=[],this.terminalCallbacks=[],this.eventCallbacks=[],this.streamCallbacks=[],this.errorCallbacks=[],this.streams=new Map,this.artifacts=[],this.streamWaiters=[],this.terminalWaiters=[],this.closed=!1,this.listener=null,this.terminalReceived=!1,this.drainTimer=null,this.openStreamClients=new Set,this.seenTimetokens=new Set,this.taskId=t.taskId,this.ownerId=t.ownerId,this.orgId=t.orgId??t.ownerId,this.readToken=t.readToken,this.agentName=t.agentName,this.pubnub=t.pubnub,this.ownsSubscribeClient=t.ownsSubscribeClient??!1,this.sdkOptions=t.sdkOptions,this.rpcConfig=t.rpcConfig??null,this.statusChannel=t.statusChannel??r(t.taskId,this.orgId),this.idempotent=t.idempotent,this.queued=t.queued,this.pushConfigId=t.pushConfigId,this.autoDrain=t.autoDrain??!0,this.drainWindowMs=t.drainWindowMs??3e4,this.state=t.state,this.skipSubscriptionMode=t.skipSubscription??!1,this.subscribeKey=t.sdkOptions.subscribeKey,this.publishKey=t.sdkOptions.publishKey??"",t.preloadedStreams)for(const[e,r]of t.preloadedStreams){const t=new s(r.descriptor,this.sdkOptions,{onOpen:t=>this.trackStreamClient(t),sessionState:()=>this.state});this.streams.set(e,t)}t.preloadedArtifacts&&this.artifacts.push(...t.preloadedArtifacts),t.preClosed?this.closed=!0:t.skipSubscription||(t.externalSubscription?(this.listener=t.externalSubscription.listener,t.externalSubscription.onReady(this.handleEvent.bind(this))):this.setupSubscription())}setupSubscription(){const t=this.pubnub,e=this.statusChannel;this.listener={message:t=>{if(t.channel!==e)return;const s=t.message;if(!s||"object"!=typeof s||!s.type)return;const r=null!=t.timetoken?String(t.timetoken):void 0;this.handleEvent(s,r)}},t.addListener(this.listener),t.subscribe({channels:[e],timetoken:1e3})}routeCallbackError(t,e,s){const r=t instanceof Error?t:new Error(String(t));if(this.errorCallbacks.length>0)for(const t of this.errorCallbacks)try{t(r,{entryPoint:"taskSession",callbackType:e,event:s})}catch{}else console.warn(`[TaskSession] callback error in ${e}:`,r.message)}handleEvent(t,e){if(!this.closed){if(e){if(this.seenTimetokens.has(e))return;if(this.seenTimetokens.add(e),this.seenTimetokens.size>TaskSession.SEEN_TIMETOKENS_MAX){const t=this.seenTimetokens.values().next().value;void 0!==t&&this.seenTimetokens.delete(t)}}for(const e of this.eventCallbacks)try{e(t)}catch(e){this.routeCallbackError(e,"onEvent",t)}switch(t.type){case"progress":for(const e of this.progressCallbacks)try{e(t)}catch(e){this.routeCallbackError(e,"onProgress",t)}"stream_started"===t.streamEvent&&t.streams&&this.handleStreamStarted(t);break;case"artifact":this.accumulateArtifact(t);for(const e of this.artifactCallbacks)try{e(t)}catch(e){this.routeCallbackError(e,"onArtifact",t)}break;case"terminal":this.state=t.state;for(const e of this.terminalCallbacks)try{e(t)}catch(e){this.routeCallbackError(e,"onTerminal",t)}for(const e of this.terminalWaiters)e.resolve(t);this.terminalWaiters=[],this.autoDrain?this.startAutoDrain():this.close()}}}trackStreamClient(t){this.openStreamClients.add(t),t.onInboundDone(()=>{this.openStreamClients.delete(t),t.isActive&&t.end().catch(()=>{}),this.terminalReceived&&0===this.openStreamClients.size&&(this.drainTimer&&(clearTimeout(this.drainTimer),this.drainTimer=null),this.close())})}accumulateArtifact(t){const e=t.artifactRef;e&&"object"==typeof e&&e.kind&&this.artifacts.push(e)}handleStreamStarted(t){const r=t.streams;if(!r||"object"!=typeof r)return;const i=t.declaredStream;for(const[t,a]of Object.entries(r)){if(!a||"object"!=typeof a)continue;if(this.streams.has(t))continue;const r=a.direction,n=e(r),o=a.format;if(!o||"bytes"!==o&&"events"!==o)continue;const l=a.affinity;if("dedicated"!==l&&"shared"!==l){console.warn(`[TaskSession] live stream_started: dropping stream "${t}" for task "${this.taskId}" — invalid or missing affinity (got ${JSON.stringify(a.affinity)})`);continue}const c={taskId:this.taskId,streamId:t,agentName:this.agentName,channel:a.channel,token:a.token,agentDirection:r,localDirection:n,format:o,affinity:l,metadata:a.metadata,declaredStream:i},h=new s(c,this.sdkOptions,{onOpen:t=>this.trackStreamClient(t),sessionState:()=>this.state});this.streams.set(t,h);for(const t of this.streamCallbacks)try{t(h)}catch(t){this.routeCallbackError(t,"onStream",h)}this.resolveWaiters(h)}}startAutoDrain(){this.closed||(this.terminalReceived=!0,0!==this.openStreamClients.size?this.drainTimer=setTimeout(()=>{this.drainTimer=null;for(const t of this.openStreamClients)t.isActive&&t.end().catch(()=>{});this.close()},this.drainWindowMs):this.close())}findStreamByIdOrDeclared(t){const e=this.streams.get(t);if(e)return e;for(const e of this.streams.values())if(e.descriptor.declaredStream===t)return e}resolveWaiters(t){const e=[];for(const s of this.streamWaiters){let r=!1;if(void 0!==s.streamId)r=t.descriptor.declaredStream===s.streamId||t.descriptor.streamId===s.streamId;else if(s.predicate)try{r=s.predicate(t)}catch(e){this.routeCallbackError(e,"streamPredicate",t)}else r=!0;r?s.resolve(t):e.push(s)}this.streamWaiters=e}onProgress(t){return this.progressCallbacks.push(t),()=>{this.progressCallbacks=this.progressCallbacks.filter(e=>e!==t)}}onArtifact(t){return this.artifactCallbacks.push(t),()=>{this.artifactCallbacks=this.artifactCallbacks.filter(e=>e!==t)}}onTerminal(t){return this.terminalCallbacks.push(t),()=>{this.terminalCallbacks=this.terminalCallbacks.filter(e=>e!==t)}}onEvent(t){return this.eventCallbacks.push(t),()=>{this.eventCallbacks=this.eventCallbacks.filter(e=>e!==t)}}onError(t){return this.errorCallbacks.push(t),()=>{this.errorCallbacks=this.errorCallbacks.filter(e=>e!==t)}}listArtifacts(){return[...this.artifacts]}async downloadArtifact(e){if(this.pubnub)return a(e,this.pubnub);const s=`blocks-dl-${Date.now().toString(36)}-${Math.random().toString(36).slice(2,6)}`,r=new t({subscribeKey:this.subscribeKey,publishKey:this.publishKey||void 0,userId:s});this.readToken&&r.setToken(this.readToken);try{return await a(e,r)}finally{r.destroy()}}onStream(t){this.streamCallbacks.push(t);for(const e of this.streams.values())try{t(e)}catch(t){this.routeCallbackError(t,"onStream",e)}return()=>{this.streamCallbacks=this.streamCallbacks.filter(e=>e!==t)}}listStreams(){return[...this.streams.values()]}openAllStreams(t){const e=[];for(const s of this.streams.values()){const r=s.descriptor.localDirection;if("inbound"===r||"bidirectional"===r)try{e.push(s.open(t))}catch{}}return e}waitForStream(t){if(this.closed)return Promise.reject(new Error("TaskSession is closed"));if(this.skipSubscriptionMode){if(void 0!==t){const e=this.findStreamByIdOrDeclared(t);if(e)return Promise.resolve(e)}else{if(1===this.streams.size)return Promise.resolve(this.streams.values().next().value);if(this.streams.size>1)return Promise.reject(new Error(`Multiple streams exist (${this.streams.size}). Use waitForStream(streamId) or waitForStreamWhere(predicate) to select one.`))}return Promise.reject(new Error("No matching stream found. This is a terminal task session with no live subscription -- no future stream announcements will arrive."))}if(void 0!==t){const e=this.findStreamByIdOrDeclared(t);if(e)return Promise.resolve(e)}else{if(1===this.streams.size)return Promise.resolve(this.streams.values().next().value);if(this.streams.size>1)return Promise.reject(new Error(`Multiple streams exist (${this.streams.size}). Use waitForStream(streamId) or waitForStreamWhere(predicate) to select one.`))}return new Promise((e,s)=>{this.streamWaiters.push({resolve:e,reject:s,streamId:t})})}waitForStreamWhere(t){if(this.closed)return Promise.reject(new Error("TaskSession is closed"));for(const e of this.streams.values())try{if(t(e))return Promise.resolve(e)}catch(t){this.routeCallbackError(t,"streamPredicate",e)}return this.skipSubscriptionMode?Promise.reject(new Error("No matching stream found. This is a terminal task session with no live subscription -- no future stream announcements will arrive.")):new Promise((e,s)=>{this.streamWaiters.push({resolve:e,reject:s,predicate:t})})}async waitForTerminal(t){if(this.state&&TERMINAL_STATES.has(this.state))return{type:"terminal",taskId:this.taskId,state:this.state};if(this.closed)throw new Error("TaskSession closed");return new Promise((e,s)=>{const r={resolve:e,reject:s};if(this.terminalWaiters.push(r),void 0!==t){const e=setTimeout(()=>{const e=this.terminalWaiters.indexOf(r);-1!==e&&this.terminalWaiters.splice(e,1),s(new Error(`waitForTerminal timed out after ${t}ms`))},t),i=r.resolve,a=r.reject;r.resolve=t=>{clearTimeout(e),i(t)},r.reject=t=>{clearTimeout(e),a(t)}}})}async saveArtifacts(t){const{mkdirSync:e,writeFileSync:s}=await import("node:fs"),{join:r,resolve:i,basename:a}=await import("node:path"),n=i(t);e(n,{recursive:!0});const o=[],l=this.listArtifacts();for(let t=0;t<l.length;t++){const e=await this.downloadArtifact(l[t]),c=e.fileName??`artifact-${t}`,h=i(r(n,a(c)||`artifact-${t}`));if(!h.startsWith(n+"/")&&h!==n)throw new Error(`Artifact filename "${c}" resolves outside target directory`);s(h,e.data),o.push(h)}return o}async cancel(){if(!this.rpcConfig)throw new Error("TaskSession was not created with RPC config; use TaskClient.cancelTask() directly");await i(this.rpcConfig,"CancelTask",{taskId:this.taskId})}async terminate(){if(!this.rpcConfig)throw new Error("TaskSession was not created with RPC config; use TaskClient.terminateTask() directly");await i(this.rpcConfig,"TerminateTask",{taskId:this.taskId})}close(){if(this.closed)return;this.closed=!0,this.drainTimer&&(clearTimeout(this.drainTimer),this.drainTimer=null);for(const t of this.openStreamClients)t.isActive&&t.end().catch(()=>{});this.openStreamClients.clear();const t=new Error("TaskSession closed");for(const e of this.streamWaiters)e.reject(t);this.streamWaiters=[];for(const e of this.terminalWaiters)e.reject(t);this.terminalWaiters=[],this.pubnub&&(this.listener&&(this.pubnub.removeListener(this.listener),this.listener=null),this.pubnub.unsubscribe({channels:[this.statusChannel]}),this.ownsSubscribeClient&&this.pubnub.destroy()),this.progressCallbacks=[],this.artifactCallbacks=[],this.terminalCallbacks=[],this.eventCallbacks=[],this.streamCallbacks=[],this.errorCallbacks=[]}async asyncClose(){if(this.closed)return;const t=[...this.openStreamClients].filter(t=>t.isActive).map(t=>t.end().catch(()=>{}));await Promise.all(t),this.openStreamClients.clear(),this.close()}async[Symbol.asyncDispose](){await this.asyncClose()}get isClosed(){return this.closed}}TaskSession.SEEN_TIMETOKENS_MAX=200;

package/dist/runtime/write-affinity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Write-affinity header tracking for non-browser clients.
+ *
+ * The backend returns X-Write-Affinity (Unix timestamp) on successful
+ * mutations. Echoing it on subsequent requests forces reads from
+ * primary during the affinity window, avoiding stale replica reads
+ * after a write.
+ *
+ * Module-level state — affinity is per-process, not per-user.
+ *
+ * Concurrency: JS is single-threaded, so function bodies run atomically and
+ * no lock is needed. However, async response ordering means `capture(newer)`
+ * followed by `capture(older)` could otherwise shorten the affinity window.
+ * Capture is therefore monotonic — an older expiry never overwrites a newer
+ * one — so out-of-order response completions are safe.
+ */
+/** Capture the affinity header from a fetch Response. Monotonic — newer wins. */
+export declare function captureAffinity(headers: Headers | undefined): void;
+/** Inject, or strip, the affinity header on an outgoing request. */
+export declare function injectAffinity(headers: Record<string, string>): void;
+/** Reset stored affinity (for tests). */
+export declare function resetAffinity(): void;

package/dist/runtime/write-affinity.js

@@ -0,0 +1 @@
+const t="x-write-affinity";let n=null,e=0;export function captureAffinity(i){if(!i||"function"!=typeof i.get)return;const f=i.get(t);if(!f)return;const o=Number(f);Number.isFinite(o)&&o>e&&(n=f,e=o)}export function injectAffinity(i){n&&e>Date.now()/1e3?i[t]=n:(n&&(n=null,e=0),delete i[t])}export function resetAffinity(){n=null,e=0}

package/dist/runtime/write-affinity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/write-affinity.test.js

@@ -0,0 +1 @@
+import{describe as e,it as t,expect as i,beforeEach as n}from"vitest";import{captureAffinity as a,injectAffinity as r,resetAffinity as o}from"./write-affinity.js";e("write-affinity",()=>{n(()=>{o()}),t("injects nothing when no affinity has been captured",()=>{const e={};r(e),i(e).toEqual({})}),t("captures and injects a valid affinity header",()=>{const e=String(Math.floor(Date.now()/1e3)+10);a(new Headers({"x-write-affinity":e}));const t={};r(t),i(t["x-write-affinity"]).toBe(e)}),t("does not inject an expired affinity header",()=>{const e=String(Math.floor(Date.now()/1e3)-10);a(new Headers({"x-write-affinity":e}));const t={};r(t),i(t).toEqual({})}),t("ignores missing header in response",()=>{a(new Headers);const e={};r(e),i(e).toEqual({})}),t("overwrites older affinity with newer one",()=>{const e=String(Math.floor(Date.now()/1e3)+5),t=String(Math.floor(Date.now()/1e3)+15);a(new Headers({"x-write-affinity":e})),a(new Headers({"x-write-affinity":t}));const n={};r(n),i(n["x-write-affinity"]).toBe(t)}),t("capture is monotonic — older arriving after newer is ignored",()=>{const e=String(Math.floor(Date.now()/1e3)+15),t=String(Math.floor(Date.now()/1e3)+5);a(new Headers({"x-write-affinity":e})),a(new Headers({"x-write-affinity":t}));const n={};r(n),i(n["x-write-affinity"]).toBe(e)}),t("strips stale header from a reused headers object when state has expired",()=>{const e=String(Math.floor(Date.now()/1e3)+10),t={};a(new Headers({"x-write-affinity":e})),r(t),i(t["x-write-affinity"]).toBe(e),o(),r(t),i(t["x-write-affinity"]).toBeUndefined()}),t("strips pre-populated header when no state has been captured",()=>{const e={"x-write-affinity":"1234567890"};r(e),i(e["x-write-affinity"]).toBeUndefined()}),t.each(["Infinity","-Infinity","NaN","not-a-number"])("malformed header value %s does not clobber existing valid state",e=>{const t=String(Math.floor(Date.now()/1e3)+10);a(new Headers({"x-write-affinity":t})),a(new Headers({"x-write-affinity":e}));const n={};r(n),i(n["x-write-affinity"]).toBe(t)})});

package/dist/stream/bytes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Browser-safe byte utilities for the Stream SDK.
+ *
+ * Replaces Node.js Buffer usage with Uint8Array, TextEncoder, and
+ * TextDecoder, which work identically in browsers and Node.js.
+ */
+export declare function utf8ByteLength(str: string): number;
+export declare function utf8Encode(str: string): Uint8Array;
+export declare function utf8Decode(bytes: Uint8Array): string;
+export declare function base64ToBytes(b64: string): Uint8Array;
+/** Convert bytes to base64. Intended for bounded stream chunks and
+ *  multipart parts (typically <16KB), not arbitrary large blobs. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function concatBytes(parts: Uint8Array[]): Uint8Array;

package/dist/stream/bytes.js

@@ -0,0 +1 @@
+const e=new TextEncoder,t=new TextDecoder;export function utf8ByteLength(t){return e.encode(t).length}export function utf8Encode(t){return e.encode(t)}export function utf8Decode(e){return t.decode(e)}export function base64ToBytes(e){const t=atob(e),n=new Uint8Array(t.length);for(let e=0;e<t.length;e++)n[e]=t.charCodeAt(e);return n}export function bytesToBase64(e){let t="";for(const n of e)t+=String.fromCharCode(n);return btoa(t)}export function concatBytes(e){const t=e.reduce((e,t)=>e+t.length,0),n=new Uint8Array(t);let o=0;for(const t of e)n.set(t,o),o+=t.length;return n}

package/dist/stream/descriptor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * StreamDescriptor type and invertDirection helper.
+ *
+ * StreamDescriptor is the plain data shape that bridges the Agent SDK
+ * (control plane) and the Stream SDK (data plane). It carries all the
+ * information needed to open a stream connection.
+ *
+ * invertDirection computes localDirection from agentDirection as
+ * delivered in stream_started events.
+ */
+import type { StreamDirection, StreamFormat } from './types.js';
+/** Stream affinity as declared on the agent card. */
+export type StreamAffinity = 'dedicated' | 'shared';
+/**
+ * Plain data shape carrying all information needed to open a stream connection.
+ *
+ * - agentDirection: what arrived on the wire in stream_started
+ * - localDirection: what the local client actually does (computed via invertDirection)
+ * - affinity: 'dedicated' (per-task channel) or 'shared' (cross-task
+ *   broadcast). Required: the stream_started wire event carries it, and
+ *   producer-side construction has it in scope from the card declaration.
+ *   Consumer-side cleanup rules consult this field to decide whether to
+ *   publish a stream_end marker on a shared channel (they must not).
+ */
+export interface StreamDescriptor {
+    taskId: string;
+    streamId: string;
+    agentName: string;
+    channel: string;
+    token: string;
+    agentDirection: StreamDirection;
+    localDirection: StreamDirection;
+    format: StreamFormat;
+    affinity: StreamAffinity;
+    metadata?: Record<string, unknown>;
+    /** The declared stream key from the agent card's streams block. */
+    declaredStream?: string;
+}
+/**
+ * Compute the local direction from the agent-facing direction delivered
+ * in stream_started.
+ *
+ * - agent outbound -> consumer inbound (consumer reads)
+ * - agent inbound -> consumer outbound (consumer writes)
+ * - agent bidirectional -> consumer bidirectional
+ */
+export declare function invertDirection(agentDirection: StreamDirection): StreamDirection;

package/dist/stream/descriptor.js

@@ -0,0 +1 @@
+export function invertDirection(n){switch(n){case"outbound":return"inbound";case"inbound":return"outbound";case"bidirectional":return"bidirectional";default:throw new Error(`Unknown direction: ${n}`)}}

package/dist/stream/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @blocks-network/sdk/stream - Public API surface.
+ *
+ * Exports the StreamClient class, StreamDescriptor type, invertDirection
+ * helper, validateStreamId validator, and all shared types.
+ */
+export { StreamClient } from './stream-client.js';
+export type { StreamError } from './stream-client.js';
+export { type StreamDescriptor, type StreamAffinity, invertDirection } from './descriptor.js';
+export { validateStreamId } from './validate.js';
+export type { StreamFormat, StreamDirection, StreamClientOptions, StreamClientFromDescriptorOptions, InboundMessage, StreamBundleConfig, } from './types.js';

package/dist/stream/index.js

@@ -0,0 +1 @@
+export{StreamClient}from"./stream-client.js";export{invertDirection}from"./descriptor.js";export{validateStreamId}from"./validate.js";

package/dist/stream/stream-bundle.d.ts

@@ -0,0 +1,82 @@
+/**
+ * StreamBundle - Internal transport engine for the Stream SDK.
+ *
+ * Accumulates write() calls into buffered bundles and publishes them to
+ * PubNub stream channels. Handles both wire formats (stream_data and
+ * stream_events), multipart splitting for oversized payloads, binary
+ * encoding, presence gating, and meta.sender on every publish.
+ *
+ * This class is internal to the Stream SDK package. The public API is
+ * StreamClient, which owns a StreamBundle instance.
+ *
+ * Wire formats:
+ *   stream_data:   { type, streamId, seq, ts, encoding, chunks }
+ *   stream_events: { type, streamId, seq, ts, encoding: "utf8", events }
+ *
+ * Sequence numbering:
+ *   stream_data starts at seq 0
+ *   stream_events starts at seq 1
+ */
+import type PubNub from 'pubnub';
+import type { StreamFormat, StreamBundleConfig } from './types.js';
+export declare class StreamBundle {
+    private readonly pubnub;
+    private readonly channel;
+    private readonly streamId;
+    private readonly format;
+    private readonly maxMessageSize;
+    private readonly bundleSizeBytes;
+    private readonly maxLatencyMs;
+    private readonly uuid;
+    private readonly gated;
+    private occupancy;
+    private presenceListener;
+    private buffer;
+    private bufferBytes;
+    private currentBatchHasBinary;
+    private eventBuffer;
+    private eventBufferSize;
+    private seq;
+    private closed;
+    private flushTimer;
+    private inflightFlushes;
+    /** Callback invoked when the stream ends. */
+    onEnd?: (() => Promise<void> | void);
+    constructor(pubnub: PubNub, channel: string, streamId: string, format: StreamFormat, config: StreamBundleConfig, gated: boolean);
+    get isActive(): boolean;
+    get consumerCount(): number;
+    /**
+     * Buffered write. Appends data to the internal buffer.
+     * Flushing happens asynchronously on size or time threshold.
+     */
+    write(data: string | Uint8Array | unknown): void;
+    /**
+     * Publish a stream_end marker on the data channel.
+     * Uses the next seq value after the final data flush.
+     * Swallows publish errors silently (terminal fallback is the safety net).
+     */
+    publishEndMarker(): Promise<void>;
+    /**
+     * Flush remaining data, clean up presence, invoke onEnd callback.
+     */
+    end(): Promise<void>;
+    private setupPresenceGating;
+    private teardownPresenceGating;
+    private writeBytes;
+    private flush;
+    private writeEvent;
+    private flushEvents;
+    private trackFlush;
+    private publishMessage;
+    /**
+     * Split an oversized message into multiple base64-encoded parts.
+     * Splitting is byte-safe: converts to Uint8Array, splits on byte
+     * boundaries, then base64-encodes each part.
+     *
+     * Publishes run with bounded concurrency (see
+     * `DEFAULT_MULTIPART_CONCURRENCY`). Part order on the wire is
+     * irrelevant — the consumer reassembles by `multipart.part` index.
+     */
+    private publishMultipart;
+    private clearTimer;
+}

package/dist/stream/stream-bundle.js

@@ -0,0 +1 @@
+import{utf8ByteLength as t,utf8Encode as e,bytesToBase64 as s}from"./bytes.js";import{CURRENT_PROTOCOL_VERSION as i}from"../runtime/protocol-version.js";export class StreamBundle{constructor(t,e,s,i,n,h){if(this.occupancy=0,this.presenceListener=null,this.buffer=[],this.bufferBytes=0,this.currentBatchHasBinary=!1,this.eventBuffer=[],this.eventBufferSize=0,this.closed=!1,this.flushTimer=null,this.inflightFlushes=[],this.pubnub=t,this.channel=e,this.streamId=s,this.format=i,n.maxMessageSize<=512)throw new Error(`maxMessageSize (${n.maxMessageSize}) must be greater than ENVELOPE_RESERVE (512)`);this.maxMessageSize=n.maxMessageSize,this.bundleSizeBytes=n.bundleSizeBytes,this.maxLatencyMs=n.maxLatencyMs,this.uuid=n.uuid,this.gated=h,this.seq="events"===i?1:0}get isActive(){return!this.closed}get consumerCount(){return this.gated?this.occupancy:0}write(t){if(this.closed)throw new Error("Cannot write to a closed stream");"events"===this.format?this.writeEvent(t):this.writeBytes(t)}async publishEndMarker(){const t={type:"stream_end",streamId:this.streamId,seq:this.seq++,ts:Date.now(),protocolVersion:i};await this.publishMessage(t).catch(()=>{})}async end(){this.closed||(this.closed=!0,this.clearTimer(),this.inflightFlushes.length>0&&(await Promise.all(this.inflightFlushes),this.inflightFlushes=[]),"events"===this.format?await this.flushEvents():await this.flush(),this.teardownPresenceGating(),await(this.onEnd?.()))}setupPresenceGating(){const t=this.channel+"-pnpres";this.presenceListener={message:e=>{e.channel===t&&"number"==typeof e.message?.occupancy&&(this.occupancy=e.message.occupancy)}},this.pubnub.addListener(this.presenceListener),this.pubnub.subscribe({channels:[t]}),this.pubnub.hereNow({channels:[this.channel]}).then(t=>{const e=t.channels?.[this.channel];e&&"number"==typeof e.occupancy&&(this.occupancy=e.occupancy)}).catch(()=>{})}teardownPresenceGating(){this.presenceListener&&(this.pubnub.removeListener(this.presenceListener),this.presenceListener=null),this.gated&&this.pubnub.unsubscribe({channels:[this.channel+"-pnpres"]})}writeBytes(e){let i;"string"==typeof e?i=e:e instanceof Uint8Array?(i=s(e),this.currentBatchHasBinary=!0):i=String(e);const n=t(i);this.buffer.push(i),this.bufferBytes+=n,this.bufferBytes>=this.bundleSizeBytes?this.trackFlush(this.flush()):null===this.flushTimer&&(this.flushTimer=setTimeout(()=>{this.flushTimer=null,this.trackFlush(this.flush())},this.maxLatencyMs))}async flush(){if(0===this.buffer.length)return;this.clearTimer();const e=this.buffer,s=this.currentBatchHasBinary;this.buffer=[],this.bufferBytes=0,this.currentBatchHasBinary=!1;const n={type:"stream_data",streamId:this.streamId,seq:this.seq++,ts:Date.now(),encoding:s?"base64":"utf8",chunks:e,protocolVersion:i},h=JSON.stringify(n);t(h)>this.maxMessageSize?await this.publishMultipart(n):await this.publishMessage(n)}writeEvent(e){if("string"==typeof e)throw new Error('write() does not accept raw strings in format: "events". Pass an object (e.g., { text: "..." }) or use format: "bytes".');e instanceof Uint8Array?(this.eventBuffer.push({$binary:s(e)}),this.eventBufferSize+=Math.ceil(4*e.length/3)+20):(this.eventBuffer.push(e),this.eventBufferSize+=t(JSON.stringify(e))),this.eventBufferSize>=this.bundleSizeBytes?this.trackFlush(this.flushEvents()):null===this.flushTimer&&(this.flushTimer=setTimeout(()=>{this.flushTimer=null,this.trackFlush(this.flushEvents())},this.maxLatencyMs))}async flushEvents(){if(0===this.eventBuffer.length)return;this.clearTimer();const e=this.eventBuffer;this.eventBuffer=[],this.eventBufferSize=0;const s={type:"stream_events",streamId:this.streamId,seq:this.seq++,ts:Date.now(),encoding:"utf8",events:e,protocolVersion:i},n=JSON.stringify(s);t(n)>this.maxMessageSize?await this.publishMultipart(s):await this.publishMessage(s)}trackFlush(t){this.inflightFlushes.push(t),t.then(()=>{const e=this.inflightFlushes.indexOf(t);e>=0&&this.inflightFlushes.splice(e,1)})}async publishMessage(t){let e=null;for(let s=1;s<=3;s++)try{return void await this.pubnub.publish({channel:this.channel,message:t,meta:{sender:this.uuid,protocolVersion:i},storeInHistory:!1,sendByPost:!0})}catch(t){if(e=t,s<3){const t=100*Math.pow(2,s-1);await new Promise(e=>setTimeout(e,t))}}console.error("[StreamBundle] Failed to publish stream message after 3 attempts:",e)}async publishMultipart(t){const n=JSON.stringify(t),h=e(n),r=Math.floor(3*(this.maxMessageSize-512)/4),a=Math.ceil(h.length/r),u=`mp-${Date.now()}-${t.seq}`,l=[];for(let e=0;e<a;e++){const n=h.subarray(e*r,(e+1)*r),c={type:t.type,streamId:this.streamId,seq:t.seq,ts:t.ts,multipart:{id:u,part:e+1,total:a},data:s(n),protocolVersion:i};l.push(()=>this.publishMessage(c))}await async function(t,e){const s=new Array(t.length);let i=0;const n=Math.min(e,t.length),h=Array.from({length:n},async()=>{for(;;){const e=i++;if(e>=t.length)return;s[e]=await t[e]()}});return await Promise.all(h),s}(l,4)}clearTimer(){null!==this.flushTimer&&(clearTimeout(this.flushTimer),this.flushTimer=null)}}

package/dist/stream/stream-client.d.ts

@@ -0,0 +1,192 @@
+/**
+ * StreamClient - The developer-facing API for the Stream SDK.
+ *
+ * Handles PubNub client creation, token setup, UUID generation, channel
+ * computation, direction routing, self-publish filtering, presence gating,
+ * and inbound message consumption with multipart reassembly.
+ *
+ * StreamClient is the public API. StreamBundle is the internal engine.
+ */
+import type { StreamDescriptor } from './descriptor.js';
+import type { StreamClientOptions, StreamClientFromDescriptorOptions, InboundMessage } from './types.js';
+/** Reset the UUID counter (for testing). */
+export declare function _resetUuidCounter(): void;
+export declare const FATAL_STREAM_ERROR_CATEGORIES: ReadonlySet<string>;
+/**
+ * Compatibility helper that detects a PubNub status error across the two
+ * shapes the pinned `pubnub@10.2.x` JS SDK exposes on the subscribe
+ * listener:
+ *
+ * - `Status` — has a required `error: boolean` and `statusCode: number`.
+ * - `StatusEvent` — has an optional polymorphic
+ *   `error?: string | StatusCategory | boolean` and no numeric status
+ *   code.
+ *
+ * Priority:
+ *   1. Truthy `status.error` (covers `true`, non-empty string, or
+ *      category-name string surfaced by `StatusEvent`).
+ *   2. Numeric `statusCode >= 400` (REST-style errors surfaced via
+ *      `Status`).
+ *   3. Fatal-category membership as a last resort when the payload is
+ *      sparse (defensive; keeps PAM detection working even if neither of
+ *      the above fields is populated by a future SDK minor release).
+ *
+ * Exported so classifier behavior can be unit-tested directly without
+ * instantiating a full `StreamClient`.
+ */
+export declare function isStreamStatusError(status: {
+    error?: unknown;
+    statusCode?: unknown;
+    category?: unknown;
+} | null | undefined): boolean;
+/** True if this category is in the fatal allowlist. */
+export declare function isFatalStreamCategory(category: string | undefined | null): boolean;
+/**
+ * Typed error payload fired to `StreamClient.onError(...)` subscribers.
+ *
+ * Fires for every PubNub status event classified as an error by
+ * `isStreamStatusError`. Consumers branch on `fatal` for
+ * must-terminate conditions (PAM revocation, bad grant) and on
+ * `category` for finer-grained UX.
+ */
+export interface StreamError {
+    /** PubNub status category (e.g., `PNAccessDeniedCategory`). */
+    category: string;
+    /** Raw PubNub error data (`errorData` or `error` payload if present). */
+    error: any;
+    /** The stream channel the error applies to. */
+    channel: string;
+    /** Unix ms timestamp when the error was observed. */
+    timestamp: number;
+    /** Whether the error triggered forced stream termination. */
+    fatal: boolean;
+}
+export declare class StreamClient {
+    private readonly pubnub;
+    private readonly bundle;
+    private readonly _channel;
+    private readonly _uuid;
+    private readonly direction;
+    private readonly format;
+    private readonly _affinity;
+    private _isActive;
+    private endCallbacks;
+    private inboundDoneCallbacks;
+    private inboundDoneFired;
+    private errorCallbacks;
+    private inboundQueue;
+    private inboundResolve;
+    private inboundDone;
+    private messageListener;
+    private multipartBuffers;
+    private nextExpectedSeq;
+    private reorderBuffer;
+    private reorderTimer;
+    private endSeq;
+    private readonly reorderTimeoutMs;
+    constructor(options: StreamClientOptions);
+    get isActive(): boolean;
+    get channel(): string;
+    get uuid(): string;
+    /**
+     * Write data to the stream.
+     * Throws if the stream is ended or direction is inbound-only.
+     */
+    write(data: string | Uint8Array | unknown): void;
+    /**
+     * Flush remaining data, unsubscribe, and destroy the PubNub client.
+     */
+    end(): Promise<void>;
+    /**
+     * Register a callback to be invoked when end() completes.
+     */
+    onEnd(callback: () => void): void;
+    /**
+     * Register a callback to fire when the inbound iterator completes for any
+     * reason: stream_end marker, explicit end(), or error. Internal only --
+     * used by TaskSession for auto-drain tracking.
+     *
+     * If the inbound side has already completed, the callback fires immediately.
+     */
+    onInboundDone(cb: () => void): void;
+    private fireInboundDone;
+    /**
+     * Register a callback to fire when the stream encounters a PubNub
+     * status error — PAM revocation, network failure, grant mismatch, etc.
+     *
+     * The callback receives a {@link StreamError} with `fatal: true` when
+     * the error caused forced stream termination (and `onInboundDone` will
+     * fire shortly after so consumer iterators exit cleanly). Non-fatal
+     * errors fire with `fatal: false` and leave the stream running so
+     * PubNub's retry machinery can recover.
+     *
+     * Consumer exceptions from the callback are swallowed and logged; they
+     * do not interrupt stream teardown.
+     */
+    onError(callback: (err: StreamError) => void): void;
+    private fireError;
+    /**
+     * Async iterable of inbound messages. Throws if direction is outbound-only.
+     * Handles multipart reassembly transparently.
+     */
+    get inbound(): AsyncIterable<InboundMessage>;
+    private setupInbound;
+    /**
+     * Dispatch a PubNub status event to `onError` subscribers, then
+     * force-terminate the stream if the category is in the fatal
+     * allowlist. Non-error / benign status events are ignored.
+     *
+     * All work is wrapped in try/catch so a listener exception can't
+     * destabilize PubNub's internal event loop.
+     */
+    private handleStatusEvent;
+    private handleInboundMessage;
+    private handleMultipartPart;
+    /** Remove a multipart group from the buffer. */
+    private dropMultipartGroup;
+    /** Evict groups older than TTL or when buffer exceeds capacity. */
+    private evictStaleGroups;
+    private normalizeMessage;
+    private enqueueInbound;
+    private enqueueReordered;
+    private flushConsecutive;
+    private startReorderTimer;
+    /**
+     * Called after flushing consecutive messages. If the gap that started
+     * the current timer has been resolved but a new gap exists, cancel
+     * the old timer and start a fresh one for the new gap. If no gaps
+     * remain, just cancel.
+     */
+    private cancelAndRestartTimerIfNeeded;
+    private checkEndReached;
+    /**
+     * Decoded byte iterator. Each yield is a Uint8Array of decoded data.
+     * Handles base64 and utf-8 encoding transparently. Browser-safe: uses
+     * TextEncoder / atob via ./bytes.js helpers, no Buffer dependency.
+     */
+    bytes(): AsyncIterable<Uint8Array>;
+    /**
+     * Flattened event iterator. Each yield is a single event object
+     * unwrapped from batched event arrays.
+     */
+    events<T = unknown>(): AsyncIterable<T>;
+    /**
+     * Node Readable adapter for pipe() integration.
+     * Creates ONE persistent bytes() iterator and pumps from it across
+     * read() calls. This ensures backpressure/resume continues the same
+     * stream rather than restarting.
+     *
+     * Uses dynamic import of node:stream to avoid breaking browser bundles.
+     */
+    readable(): Promise<import('node:stream').Readable>;
+    /**
+     * Create a StreamClient from a StreamDescriptor.
+     *
+     * This is the primary public entry point for descriptor-based construction.
+     * Used internally by StreamRef.open() and directly by advanced callers.
+     *
+     * Consumer gating policy: when localDirection includes writing and gating
+     * is not explicitly set, defaults to gating: false.
+     */
+    static fromDescriptor(descriptor: StreamDescriptor, options: StreamClientFromDescriptorOptions): StreamClient;
+}