@blocks-network/sdk 0.1.45

package/dist/runtime/credential-cache.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Task Credential Cache
+ *
+ * In-memory map that survives pipe-task handler exit. Caches ownerId,
+ * writeToken (T2), and associated streamIds for each task so that
+ * instance-level APIs (publishTerminal, failStream) can operate after
+ * the per-task PubNub client is destroyed.
+ *
+ * Lifecycle:
+ * - Populated during task setup from StartTask message.
+ * - StreamIds added via addStream() during createStream() calls.
+ * - Survives pipe-task handler exit.
+ * - Removed when the task reaches terminal state.
+ * - Not persisted across process restart.
+ */
+export interface CachedCredentials {
+    ownerId: string;
+    orgId: string;
+    writeToken: string;
+    agentName: string;
+    environment: string;
+    streamIds: Set<string>;
+}
+export declare class CredentialCache {
+    private readonly entries;
+    /** Store credentials for a task. */
+    set(taskId: string, creds: Omit<CachedCredentials, 'streamIds'>): void;
+    /** Get cached credentials for a task. */
+    get(taskId: string): CachedCredentials | undefined;
+    /** Add a stream ID to a task's cache entry. */
+    addStream(taskId: string, streamId: string): void;
+    /** Remove a task's cache entry entirely. */
+    remove(taskId: string): void;
+    /** Check if a task has cached credentials. */
+    has(taskId: string): boolean;
+    /** Get all task IDs with cached credentials. */
+    taskIds(): string[];
+    /** Clear all entries. */
+    clear(): void;
+}

package/dist/runtime/credential-cache.js

@@ -0,0 +1 @@
+export class CredentialCache{constructor(){this.entries=new Map}set(e,t){const r=this.entries.get(e);if(r)return r.ownerId=t.ownerId,r.orgId=t.orgId,r.writeToken=t.writeToken,r.agentName=t.agentName,void(r.environment=t.environment);this.entries.set(e,{...t,streamIds:new Set})}get(e){return this.entries.get(e)}addStream(e,t){const r=this.entries.get(e);r&&r.streamIds.add(t)}remove(e){this.entries.delete(e)}has(e){return this.entries.has(e)}taskIds(){return[...this.entries.keys()]}clear(){this.entries.clear()}}

package/dist/runtime/file-input.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Normalize a consumer-supplied file input into a form the SDK can
+ * hand to `buildArtifactRef` (which wants `Uint8Array`) and
+ * `uploadToStorage` (which wants a `Blob`-or-bytes).
+ *
+ * Accepts the four shapes a browser or Node consumer might provide:
+ *   - `Uint8Array` (including Node `Buffer`, which extends Uint8Array).
+ *   - `ArrayBuffer`.
+ *   - `Blob` (browser-native; also available in Node 18+).
+ *   - `File` (browser-native subclass of Blob; also Node 20+).
+ *
+ * Returned shape is a three-field handle:
+ *   - `size`: byte length, available synchronously for every input
+ *     shape (the caller uses it to choose inline vs upload path).
+ *   - `uploadBody`: the canonical body to hand to `uploadToStorage`.
+ *     Blobs pass through unchanged — no pre-copy. Uint8Array /
+ *     ArrayBuffer inputs are returned as raw bytes so
+ *     `uploadToStorage` can wrap them in a Blob on demand.
+ *   - `getBytes()`: a lazy accessor that returns a `Uint8Array` view
+ *     of the input contents. For `Uint8Array` / `ArrayBuffer` inputs
+ *     it's effectively free; for `Blob` / `File` inputs it performs
+ *     one `arrayBuffer()` read, cached against repeat calls. Callers
+ *     on the upload path **MUST NOT** call `getBytes()`, because it
+ *     pulls the full Blob into memory — that defeats the streaming
+ *     upload. `getBytes()` exists only for the inline-artifact path
+ *     (files under `shouldInlineArtifact()` threshold, default 16 KB).
+ *
+ * Throws `TypeError` for unsupported inputs synchronously — malformed
+ * shapes surface immediately at call site rather than at first
+ * `getBytes()`.
+ */
+export interface NormalizedFileInput {
+    readonly size: number;
+    readonly uploadBody: Uint8Array | Blob;
+    getBytes(): Promise<Uint8Array>;
+}
+export declare function normalizeFileInput(input: Uint8Array | ArrayBuffer | Blob | File): NormalizedFileInput;

package/dist/runtime/file-input.js

@@ -0,0 +1 @@
+export function normalizeFileInput(e){if(e instanceof Uint8Array)return{size:e.byteLength,uploadBody:e,getBytes:async()=>e};if(e instanceof ArrayBuffer){const r=new Uint8Array(e);return{size:r.byteLength,uploadBody:r,getBytes:async()=>r}}if("undefined"!=typeof Blob&&e instanceof Blob){let r;return{size:e.size,uploadBody:e,getBytes:async()=>(r||(r=new Uint8Array(await e.arrayBuffer())),r)}}throw new TypeError("Unsupported file input: expected Uint8Array, ArrayBuffer, Blob, or File")}

package/dist/runtime/file-upload.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Shared pre-signed URL upload helper for the task artifacts initiative.
+ *
+ * Implements the three-step upload handshake:
+ *   1. request-upload  -> Backend returns uploadUrl, formFields, uploadId
+ *   2. S3 multipart POST -> SDK uploads directly to PubNub Files storage
+ *   3. confirm-upload  -> Backend validates and returns result
+ *
+ * Used by both consumer input (task-client.ts) and provider output
+ * (agent-instance.ts). File bytes never flow through the backend.
+ */
+import type { AgentAuth } from './agent-auth.js';
+import type { AuthProvider } from './auth-provider.js';
+/** Fields returned by the backend for direct S3 upload. */
+export interface UploadFormField {
+    key: string;
+    value: string;
+}
+/** Response from POST /api/v1/files/request-upload (consumer input). */
+export interface RequestUploadResponseConsumer {
+    uploadSessionId: string;
+    uploadId: string;
+    uploadUrl: string;
+    formFields: UploadFormField[];
+}
+/** Response from POST /api/v1/files/request-upload (provider output). */
+export interface RequestUploadResponseProvider {
+    uploadId: string;
+    uploadUrl: string;
+    formFields: UploadFormField[];
+}
+/** Response from POST /api/v1/files/confirm-upload (consumer input). */
+export interface ConfirmUploadResponseConsumer {
+    uploadId: string;
+}
+/** Response from POST /api/v1/files/confirm-upload (provider output). */
+export interface ConfirmUploadResponseProvider {
+    uploadId: string;
+    artifactRef: {
+        kind: 'file';
+        channel: string;
+        mimeType: string;
+        size: number;
+        fileId: string;
+        fileName: string;
+        hash?: string;
+        expiresAt?: string;
+    };
+}
+/** Parameters for a consumer-input request-upload call. */
+export interface ConsumerUploadParams {
+    role: 'consumer-input';
+    agentName: string;
+    fileName: string;
+    fileSize: number;
+    mimeType: string;
+    partId: string;
+    uploadSessionId?: string;
+}
+/** Parameters for a provider-output request-upload call. */
+export interface ProviderUploadParams {
+    role: 'provider-output';
+    taskId: string;
+    fileName: string;
+    fileSize: number;
+    mimeType: string;
+    outputId?: string;
+}
+/** Auth context for making backend HTTP calls. */
+export interface FileUploadAuth {
+    baseUrl: string;
+    authProvider?: AuthProvider;
+    agentAuth?: AgentAuth;
+}
+/**
+ * Request a pre-signed upload URL from the backend.
+ * Returns the upload URL, form fields, upload ID, and (for consumer input)
+ * the upload session ID.
+ */
+export declare function requestUpload(auth: FileUploadAuth, params: ConsumerUploadParams): Promise<RequestUploadResponseConsumer>;
+export declare function requestUpload(auth: FileUploadAuth, params: ProviderUploadParams): Promise<RequestUploadResponseProvider>;
+/**
+ * Upload file data directly to PubNub Files storage via S3 pre-signed URL.
+ * Constructs a multipart/form-data body with all form fields first,
+ * then appends the file as the last field named "file".
+ *
+ * Uses the native `FormData` + `Blob` types available in both Node 18+
+ * and all modern browsers. `fetch` computes the multipart boundary
+ * automatically -- do NOT set `Content-Type` manually.
+ *
+ * Returns void on success (S3 returns 204 No Content).
+ * Throws on failure (e.g., 400 EntityTooLarge for oversized files).
+ */
+export declare function uploadToStorage(uploadUrl: string, formFields: UploadFormField[], fileData: Uint8Array | ArrayBuffer | Blob, fileName: string, mimeType: string): Promise<void>;
+/**
+ * Confirm a completed upload with the backend.
+ *
+ * For consumer input: returns { uploadId }.
+ * For provider output: the backend publishes the typed artifact event
+ * on the task channel and returns { uploadId, artifactRef }.
+ */
+export declare function confirmUpload(auth: FileUploadAuth, uploadId: string): Promise<ConfirmUploadResponseConsumer>;
+export declare function confirmUpload(auth: FileUploadAuth, uploadId: string, expectArtifactRef: true): Promise<ConfirmUploadResponseProvider>;
+/**
+ * Run the complete three-step upload flow for a single file.
+ * Shared by consumer input and provider output paths.
+ */
+export declare function uploadFile(auth: FileUploadAuth, params: ConsumerUploadParams, fileData: Uint8Array | ArrayBuffer | Blob): Promise<{
+    uploadSessionId: string;
+    uploadId: string;
+}>;
+export declare function uploadFile(auth: FileUploadAuth, params: ProviderUploadParams, fileData: Uint8Array | ArrayBuffer | Blob): Promise<ConfirmUploadResponseProvider>;

package/dist/runtime/file-upload.js

@@ -0,0 +1 @@
+import{CURRENT_PROTOCOL_VERSION as t,PROTOCOL_VERSION_HEADER as o}from"./protocol-version.js";import{captureAffinity as a,injectAffinity as e}from"./write-affinity.js";async function r(r,n,i){const s=`${r.baseUrl.replace(/\/+$/,"")}${n}`,u=a=>{const n={"Content-Type":"application/json",[o]:t},s=r.authProvider?.getAuthHeader();return s&&(n.Authorization=s),a&&e(n),{method:"POST",headers:n,body:JSON.stringify(i)}};if(r.agentAuth)return r.agentAuth.authenticatedFetch(s,u(!1));const d=await fetch(s,u(!0));if(a(d.headers),401===d.status&&r.authProvider){if(await r.authProvider.onAuthFailure()){const t=await fetch(s,u(!0));return a(t.headers),t}}return d}export async function requestUpload(t,o){const a=await r(t,"/api/v1/files/request-upload",o);if(!a.ok){const t=await a.text().catch(()=>"");throw new Error(`request-upload failed: HTTP ${a.status} ${t}`)}return a.json()}export async function uploadToStorage(t,o,a,e,r){const n=new FormData;for(const t of o)n.append(t.key,t.value);const i=a instanceof Blob?a:new Blob([a],{type:r});n.append("file",i,e);const s=await fetch(t,{method:"POST",body:n});if(!s.ok){const t=await s.text().catch(()=>"");throw new Error(`S3 upload failed: HTTP ${s.status} ${t}`)}}export async function confirmUpload(t,o,a){const e=await r(t,"/api/v1/files/confirm-upload",{uploadId:o});if(!e.ok){const t=await e.text().catch(()=>"");throw new Error(`confirm-upload failed: HTTP ${e.status} ${t}`)}return e.json()}export async function uploadFile(t,o,a){const e=await requestUpload(t,o);if(await uploadToStorage(e.uploadUrl,e.formFields,a,o.fileName,o.mimeType),"provider-output"===o.role){return await confirmUpload(t,e.uploadId,!0)}const r=e;return await confirmUpload(t,e.uploadId),{uploadSessionId:r.uploadSessionId,uploadId:e.uploadId}}

package/dist/runtime/part-helpers.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Part builder helpers for constructing SendMessageRequestPart objects.
+ *
+ * These simplify the consumer experience by handling wire format field
+ * names and file reading automatically.
+ *
+ * Browser-safe: no top-level `node:fs` import. The Node-only
+ * `filePartFromPath` helper lazy-imports `node:fs` on call so browser
+ * bundlers can tree-shake it out of consumer bundles that don't use
+ * filesystem paths.
+ */
+import type { SendMessageRequestPart } from './task-client.js';
+/**
+ * Build a text request part.
+ *
+ * @param text The text content.
+ * @param partId The part ID (defaults to 'text'). Must match a declared
+ *               io.inputs[].id in the agent's card.
+ */
+export declare function textPart(text: string, partId?: string): SendMessageRequestPart;
+/**
+ * Build a file request part from raw file data.
+ *
+ * Universal: works in both Node and browser. No filesystem access.
+ * For Node-only file-path convenience, use `filePartFromPath`.
+ *
+ * Accepts `Uint8Array`, `ArrayBuffer`, `Blob`, or `File`. Browser
+ * consumers can pass a `File` from `<input type="file">` directly.
+ *
+ * @param data Raw file data.
+ * @param options Optional overrides for partId, fileName, and contentType.
+ */
+export declare function filePart(data: Uint8Array | ArrayBuffer | Blob | File, options?: {
+    partId?: string;
+    fileName?: string;
+    contentType?: string;
+}): SendMessageRequestPart;
+/**
+ * Build a file request part from a filesystem path (Node-only).
+ *
+ * Lazy-imports `node:fs` on first call so this helper can coexist
+ * with browser bundlers without pulling `node:fs` into the bundle.
+ * Not available in browsers.
+ *
+ * @param path Filesystem path.
+ * @param options Optional overrides for partId, fileName, and contentType.
+ */
+export declare function filePartFromPath(path: string, options?: {
+    partId?: string;
+    fileName?: string;
+    contentType?: string;
+}): Promise<SendMessageRequestPart>;

package/dist/runtime/part-helpers.js

@@ -0,0 +1 @@
+function e(e){const t=Math.max(e.lastIndexOf("/"),e.lastIndexOf("\\"));return t>=0?e.slice(t+1):e}export function textPart(e,t="text"){return{partId:t,text:e}}export function filePart(e,t){const n=t?.partId??"file",i="undefined"!=typeof File&&e instanceof File?e.name:void 0,a="undefined"!=typeof Blob&&e instanceof Blob&&e.type?e.type:void 0;return{partId:n,file:e,fileName:t?.fileName??i??"file",contentType:t?.contentType??a??"application/octet-stream"}}export async function filePartFromPath(t,n){const{readFileSync:i}=await import("node:fs"),a=i(t),o=new Uint8Array(a);return{partId:n?.partId??"file",file:o,fileName:n?.fileName??e(t),contentType:n?.contentType??"application/octet-stream"}}

package/dist/runtime/protocol-version.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Protocol versioning constants and helpers for the Blocks Node SDK.
+ *
+ * Centralizes the protocol version contract so no other file needs to
+ * hardcode version strings or header names.
+ */
+/** Current protocol version used by this SDK build. */
+export declare const CURRENT_PROTOCOL_VERSION = "2026-05-01";
+/** All protocol versions this SDK can speak. */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+/** Protocol versions that are deprecated but still functional. */
+export declare const DEPRECATED_PROTOCOL_VERSIONS: readonly string[];
+/** HTTP header name for protocol version negotiation. */
+export declare const PROTOCOL_VERSION_HEADER = "Blocks-Protocol-Version";
+/** SDK package version (kept in sync with package.json manually). */
+export declare const SDK_VERSION = "0.1.27";
+/** Check whether a given protocol version is supported by this SDK. */
+export declare function isProtocolVersionSupported(version: string): boolean;

package/dist/runtime/protocol-version.js

@@ -0,0 +1 @@
+export const CURRENT_PROTOCOL_VERSION="2026-05-01";export const SUPPORTED_PROTOCOL_VERSIONS=["2026-05-01"];export const DEPRECATED_PROTOCOL_VERSIONS=[];export const PROTOCOL_VERSION_HEADER="Blocks-Protocol-Version";export const SDK_VERSION="0.1.27";export function isProtocolVersionSupported(O){return SUPPORTED_PROTOCOL_VERSIONS.includes(O)}

package/dist/runtime/pubnub-client.d.ts

@@ -0,0 +1,8 @@
+import PubNub from 'pubnub';
+export interface PubNubClientConfig {
+    subscribeKey: string;
+    publishKey: string;
+    userId?: string;
+    presenceTimeout?: number;
+}
+export declare const createPubNubClient: (config: PubNubClientConfig) => PubNub;

package/dist/runtime/pubnub-client.js

@@ -0,0 +1 @@
+import e from"pubnub";export const createPubNubClient=r=>{if(!r.subscribeKey||!r.publishKey)throw new Error("PUBNUB keys not configured");return new e({publishKey:r.publishKey,subscribeKey:r.subscribeKey,userId:r.userId??"blocks-agent",enableEventEngine:!0,...void 0!==r.presenceTimeout?{presenceTimeout:r.presenceTimeout}:{}})};

package/dist/runtime/pubnub-types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Type definitions for PubNub SDK compatibility.
+ *
+ * The PubNub SDK has a strict `Payload` type that doesn't accept `unknown`.
+ * This file provides type-safe interfaces and helpers that work with both:
+ * - Node.js PubNub SDK (pubnub package)
+ * - PubNub Functions runtime (built-in pubnub module)
+ */
+import type PubNub from 'pubnub';
+import type { Payload } from 'pubnub';
+/**
+ * Cast any JSON-serializable object to PubNub's Payload type.
+ * Use this when publishing messages that don't strictly satisfy the Payload type.
+ */
+export declare const asPayload: (obj: Record<string, unknown>) => Payload;
+/**
+ * Cast to Payload or undefined for meta fields.
+ */
+export declare const asPayloadMeta: (obj: Record<string, unknown>) => Payload | undefined;
+/**
+ * JSON-serializable value that's compatible with PubNub's Payload type.
+ * Use this instead of `unknown` for message properties.
+ */
+export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type JsonArray = JsonValue[];
+/**
+ * Convert an object to a PubNub-compatible Payload.
+ * This is a type assertion helper that ensures type safety at the boundary.
+ */
+export declare const toPayload: <T extends JsonObject>(obj: T) => Payload;
+/**
+ * Safely cast a message from PubNub to a typed object.
+ */
+export declare const fromPayload: <T>(payload: unknown) => T;
+/**
+ * Partial PubNub client interface for publish operations.
+ * Compatible with both full SDK and Functions runtime.
+ */
+export interface PubNubPublisher {
+    publish(params: {
+        channel: string;
+        message: Payload;
+        storeInHistory?: boolean;
+        sendByPost?: boolean;
+        meta?: Payload;
+    }): Promise<{
+        timetoken: string | number;
+    }>;
+}
+/**
+ * Partial PubNub client interface for message actions.
+ */
+export interface PubNubMessageActions {
+    addMessageAction?(params: {
+        channel: string;
+        messageTimetoken: string;
+        action: {
+            type: string;
+            value: string;
+        };
+    }): Promise<unknown>;
+    getMessageActions?(params: {
+        channel: string;
+        start?: string;
+        limit?: number;
+    }): Promise<{
+        data?: Array<{
+            type: string;
+            value: string;
+            actionTimetoken?: string;
+        }>;
+    }>;
+}
+/**
+ * Message entry from fetchMessages response.
+ */
+export interface FetchedMessage {
+    message: unknown;
+    timetoken: string;
+    meta?: unknown;
+}
+/**
+ * Partial PubNub client interface for fetching message history.
+ * Uses a permissive signature to be compatible with the actual SDK's overloaded methods.
+ */
+export interface PubNubFetcher {
+    fetchMessages?(params: {
+        channels: string[];
+        count?: number;
+        start?: string;
+        end?: string;
+    }): Promise<{
+        channels?: Record<string, FetchedMessage[]>;
+    }>;
+}
+/**
+ * Type helper to safely pass PubNub to functions expecting partial interfaces.
+ * The SDK uses overloaded methods that don't directly match our simpler types.
+ */
+export declare const asPubNubFetcher: (pubnub: unknown) => PubNubFetcher | undefined;
+/**
+ * Combined partial PubNub interface for task index operations.
+ */
+export type PartialPubNubForIndex = PubNubPublisher & Partial<PubNubMessageActions> & Partial<PubNubFetcher>;
+/**
+ * Full PubNub client with all optional methods.
+ */
+export type FullPubNub = PubNub;
+/**
+ * Check if a PubNub client supports message actions.
+ */
+export declare const supportsMessageActions: (pubnub: PartialPubNubForIndex) => pubnub is PartialPubNubForIndex & Required<PubNubMessageActions>;
+/**
+ * Check if a PubNub client supports fetchMessages.
+ */
+export declare const supportsFetchMessages: (pubnub: PartialPubNubForIndex) => pubnub is PartialPubNubForIndex & Required<PubNubFetcher>;

package/dist/runtime/pubnub-types.js

@@ -0,0 +1 @@
+export const asPayload=t=>t;export const asPayloadMeta=t=>t;export const toPayload=t=>t;export const fromPayload=t=>t;export const asPubNubFetcher=t=>{if(!t||"object"!=typeof t)return;return"function"==typeof t.fetchMessages?t:void 0};export const supportsMessageActions=t=>"function"==typeof t.addMessageAction;export const supportsFetchMessages=t=>"function"==typeof t.fetchMessages;

package/dist/runtime/rpc-client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared JSON-RPC infrastructure for calling the Blocks backend RPC endpoint.
+ *
+ * Provides:
+ * - `withRetry()` — exponential-backoff retry for transient network errors
+ * - `rpcEndpoint()` — builds the RPC URL from a backend base URL
+ * - `callRpc()` — sends a JSON-RPC 2.0 request with retry and error handling
+ * - `RpcError` — structured error for JSON-RPC error responses
+ */
+import type { AgentAuth } from './agent-auth.js';
+import type { AuthProvider } from './auth-provider.js';
+export interface RpcClientConfig {
+    subscribeKey: string;
+    authProvider?: AuthProvider;
+    baseUrl?: string;
+    agentAuth?: AgentAuth;
+}
+/**
+ * Retry helper for transient network errors (DNS failures, timeouts, etc.)
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, maxRetries?: number, baseDelayMs?: number): Promise<T>;
+/**
+ * Build the RPC gateway URL from a backend base URL.
+ * baseUrl must be a root URL (e.g. http://localhost:3001).
+ */
+export declare function rpcEndpoint(subscribeKey: string, baseUrl?: string): string;
+/**
+ * Structured error for JSON-RPC error responses.
+ */
+export declare class RpcError extends Error {
+    code?: number;
+    rpcMessage: string;
+    data?: unknown;
+    constructor(rpcMessage: string, code?: number, data?: unknown);
+}
+/**
+ * Send a JSON-RPC 2.0 request to the Blocks backend RPC endpoint.
+ *
+ * Handles:
+ * - JSON-RPC envelope construction
+ * - Authorization header (Bearer token) when an auth provider supplies one
+ * - Transient-error retry via `withRetry()`
+ * - HTTP and JSON-RPC error mapping to `RpcError`
+ */
+export declare function callRpc<T>(config: RpcClientConfig, method: string, params: Record<string, unknown>): Promise<T>;

package/dist/runtime/rpc-client.js

@@ -0,0 +1 @@
+import{CURRENT_PROTOCOL_VERSION as r,PROTOCOL_VERSION_HEADER as t}from"./protocol-version.js";import{captureAffinity as e,injectAffinity as o}from"./write-affinity.js";export async function withRetry(r,t=3,e=500){let o;for(let n=0;n<t;n++)try{return await r()}catch(r){o=r;const a=String(r);if(!(a.includes("ENOTFOUND")||a.includes("ETIMEDOUT")||a.includes("ECONNRESET")||a.includes("NetworkIssues"))||n===t-1)throw r;const s=e*Math.pow(2,n)+100*Math.random();await new Promise(r=>setTimeout(r,s))}throw o}export function rpcEndpoint(r,t){return t?`${t.replace(/\/+$/,"")}/api/v1/rpc`:`https://ps.pndsn.com/v1/blocks/sub-key/${r}/rpc`}export class RpcError extends Error{constructor(r,t,e){super(`[RPC] ${r}`),this.name="RpcError",this.rpcMessage=r,this.code=t,this.data=e}}export async function callRpc(n,a,s){const i=rpcEndpoint(n.subscribeKey,n.baseUrl),c=`rpc-${Date.now()}-${Math.random().toString(36).slice(2,8)}`,h=e=>{const a={"Content-Type":"application/json",[t]:r},s=n.authProvider?.getAuthHeader();return s&&(a.Authorization=s),e&&o(a),a},u={jsonrpc:"2.0",id:c,method:a,params:s},p=async()=>{let r;if(n.agentAuth?r=await n.agentAuth.authenticatedFetch(i,{method:"POST",headers:h(!1),body:JSON.stringify(u)}):(r=await fetch(i,{method:"POST",headers:h(!0),body:JSON.stringify(u)}),e(r.headers)),!r.ok)throw new RpcError(`HTTP ${r.status}`,r.status);const t=await r.json();if(t.error){const r=t.error.data?.message??t.error.message??"Unknown RPC error";throw new RpcError(r,t.error.code,t.error.data)}return t.result};return withRetry(async()=>{try{return await p()}catch(r){if(r instanceof RpcError&&401===r.code&&n.authProvider&&!n.agentAuth){if(await n.authProvider.onAuthFailure())return p()}throw r}})}

package/dist/runtime/stream-context.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Stream Processing Context
+ *
+ * Wraps a StreamClient from the Stream SDK and manages the onActivate
+ * callback lifecycle. Each embedded stream ID maps to one processing
+ * context. The context owns the StreamClient instance and provides the
+ * stream object interface to onActivate callbacks.
+ *
+ * onActivate runs as an async task (microtask/promise) on the stream
+ * processing context, not the handler thread. Unhandled errors in
+ * onActivate trigger automatic failStream.
+ *
+ * `StreamObject.end()` is task-scoped: it delegates to the agent-instance
+ * `releaseStream(streamId, taskId)` hook, which evicts the per-task handle
+ * cache entry, releases the registry taskId, and — only when the last
+ * ref-holder releases — tears down the underlying StreamClient. On shared
+ * streams the teardown never publishes a `stream_end` marker (see
+ * SDK_CONTRACT §8.4.1a shared-affinity carve-out).
+ */
+import type { StreamClient, InboundMessage } from '../stream/index.js';
+/** Hook the agent-instance passes to the stream wrapper so `end()` can
+ * route through the registry + handle-cache eviction path. Decouples
+ * stream-context.ts from agent-instance.ts (no import cycle). */
+export interface AgentInstanceHooks {
+    releaseStream: (streamId: string, taskId: string) => Promise<void>;
+}
+/** The stream object passed to onActivate and returned from createStream. */
+export interface StreamObject {
+    readonly streamId: string;
+    readonly channel: string;
+    readonly isActive: boolean;
+    readonly external: boolean;
+    write(data: string | Uint8Array | unknown): void;
+    end(): Promise<void>;
+    readonly inbound: AsyncIterable<InboundMessage>;
+    onEnd(cb: () => void): void;
+    /** T7a token (only available on external streams). */
+    readonly token?: string;
+    /** Activate an external stream (only available on external streams). */
+    activate?(opts?: {
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+}
+export type OnActivateCallback = (stream: StreamObject) => void | Promise<void>;
+export type FailStreamCallback = (streamId: string, error: string) => Promise<void>;
+/**
+ * Create a StreamObject wrapper around a StreamClient.
+ * This is the shape passed to onActivate and returned from createStream.
+ *
+ * `hooks.releaseStream` — when provided, `end()` delegates to it so the
+ * agent-instance can run task-scoped cleanup (registry release,
+ * handle-cache eviction, affinity-gated teardown). Omit for synthetic
+ * test wrappers with no agent-instance owner — `end()` falls back to
+ * calling `client.end()` directly.
+ */
+export declare function createStreamObject(streamId: string, client: StreamClient, taskId?: string, hooks?: AgentInstanceHooks): StreamObject;
+/**
+ * Create a StreamObject for an external stream (no StreamClient).
+ * write() and inbound throw; token and activate are available.
+ */
+export declare function createExternalStreamObject(streamId: string, channel: string, t7aToken: string, activateFn: (opts?: {
+    metadata?: Record<string, unknown>;
+}) => Promise<void>): StreamObject;
+/**
+ * Run the onActivate callback on the stream processing context.
+ * Returns a promise that resolves when the callback completes.
+ * If the callback throws, the error is caught and failStream is called.
+ */
+export declare function runOnActivate(streamId: string, streamObject: StreamObject, callback: OnActivateCallback, failStreamCb: FailStreamCallback): Promise<void>;

package/dist/runtime/stream-context.js

@@ -0,0 +1 @@
+export function createStreamObject(e,t,r,n){return{get streamId(){return e},get channel(){return t.channel},get isActive(){return t.isActive},get external(){return!1},write(e){t.write(e)},async end(){n&&r?await n.releaseStream(e,r):await t.end()},get inbound(){return t.inbound},onEnd(e){t.onEnd(e)}}}export function createExternalStreamObject(e,t,r,n){let a=!1;const o=[];return{get streamId(){return e},get channel(){return t},get isActive(){return!a},get external(){return!0},write(){throw new Error("Cannot write to an external stream -- use Stream SDK directly")},async end(){a=!0;for(const e of o)e();o.length=0},get inbound(){throw new Error("Cannot read from an external stream")},onEnd(e){o.push(e)},get token(){return r},activate:n}}export function runOnActivate(e,t,r,n){return Promise.resolve().then(()=>r(t)).catch(async t=>{const r=t instanceof Error?t.message:String(t);console.error(`[StreamContext] onActivate error for stream "${e}":`,r);try{await n(e,"stream_crashed")}catch(t){console.error(`[StreamContext] failStream error for "${e}":`,t)}})}

package/dist/runtime/stream-ref.d.ts

@@ -0,0 +1,74 @@
+/**
+ * StreamRef - Consumer-side bridge between task events and Stream SDK.
+ *
+ * StreamRef wraps a StreamDescriptor and provides open() to create a
+ * StreamClient via fromDescriptor(). open() is idempotent while the
+ * stream client is active and must not create duplicate clients.
+ *
+ * When the owning `TaskSession` is in a terminal state at the time
+ * `open()` is called, the SDK short-circuits with `StreamUnavailableError`
+ * instead of constructing a dead client against an already-revoked PAM
+ * token. Stream data is live-only; on reconnect after termination, only
+ * the descriptor metadata and task artifacts remain accessible.
+ */
+import { StreamClient, type StreamDescriptor, type StreamClientFromDescriptorOptions } from '../stream/index.js';
+export { type StreamDescriptor } from '../stream/index.js';
+/**
+ * Thrown by `StreamRef.open()` when the owning session's task is in a
+ * terminal state. The error's `terminalState` field lets consumers branch
+ * programmatically; the message points at accessible alternatives
+ * (`ref.descriptor`, `session.listArtifacts()`, `session.state`).
+ */
+export declare class StreamUnavailableError extends Error {
+    readonly taskId: string;
+    readonly streamId: string;
+    readonly declaredStream?: string;
+    readonly terminalState: string;
+    constructor(message: string, fields: {
+        taskId: string;
+        streamId: string;
+        declaredStream?: string;
+        terminalState: string;
+    });
+}
+export declare class StreamRef {
+    readonly descriptor: StreamDescriptor;
+    private _client;
+    private _clientEnded;
+    private readonly _sdkOptions;
+    private readonly _onOpen?;
+    private readonly _sessionState?;
+    constructor(descriptor: StreamDescriptor, sdkOptions: StreamClientFromDescriptorOptions, hooks?: {
+        onOpen?: (client: StreamClient) => void;
+        sessionState?: () => string | undefined;
+    });
+    /**
+     * Open a StreamClient from this ref's descriptor.
+     *
+     * Resolution order (first match wins):
+     *
+     *   1. If a StreamClient was previously opened and is still active,
+     *      return that same client (idempotency). This also applies while
+     *      the session is draining after a terminal event — a consumer
+     *      that holds a live client MUST continue to receive it.
+     *   2. If the previously opened client has already ended, throw a
+     *      generic Error ("already been ended"). The terminal short-
+     *      circuit does NOT fire in this path, because "already ended"
+     *      is the more specific signal for "no new client here".
+     *   3. If the owning session's task is in a terminal state
+     *      (`completed`, `failed`, `canceled`) AND no client has ever
+     *      been constructed for this ref, throw `StreamUnavailableError`.
+     *      Stream data is live-only; use `ref.descriptor`,
+     *      `session.listArtifacts()`, or `session.state` to inspect a
+     *      terminal session.
+     *   4. Otherwise, construct a new StreamClient from the descriptor.
+     *
+     * Uses descriptor.format for the wire format. No caller-supplied format
+     * override is accepted.
+     */
+    open(options?: {
+        reorderTimeoutMs?: number;
+    }): StreamClient;
+    /** Whether this ref's stream client is currently active. */
+    get isOpen(): boolean;
+}

package/dist/runtime/stream-ref.js

@@ -0,0 +1 @@
+import{StreamClient as t}from"../stream/index.js";import{TERMINAL_STATES as e}from"./task-session.js";export class StreamUnavailableError extends Error{constructor(t,e){super(t),this.name="StreamUnavailableError",this.taskId=e.taskId,this.streamId=e.streamId,this.declaredStream=e.declaredStream,this.terminalState=e.terminalState}}export class StreamRef{constructor(t,e,s){this._client=null,this._clientEnded=!1,this.descriptor=t,this._sdkOptions=e,this._onOpen=s?.onOpen,this._sessionState=s?.sessionState}open(s){if(this._client&&this._client.isActive)return this._client;if(this._clientEnded)throw new Error(`StreamRef for "${this.descriptor.streamId}" has already been ended and cannot be reopened`);const r=this._sessionState?.();if(r&&e.has(r)){const t=this.descriptor.declaredStream??this.descriptor.streamId;throw new StreamUnavailableError(`Cannot open stream "${t}" on task "${this.descriptor.taskId}": the task is in terminal state "${r}" and stream data is live-only (not persisted after a task ends). The stream's metadata remains available on \`ref.descriptor\`; task artifacts are available via \`session.listArtifacts()\`; the final task state is in \`session.state\`.`,{taskId:this.descriptor.taskId,streamId:this.descriptor.streamId,declaredStream:this.descriptor.declaredStream,terminalState:r})}const i=void 0!==s?.reorderTimeoutMs?{...this._sdkOptions,reorderTimeoutMs:s.reorderTimeoutMs}:this._sdkOptions,a=t.fromDescriptor(this.descriptor,i);return a.onEnd(()=>{this._clientEnded=!0,this._client=null}),this._client=a,this._onOpen?.(a),a}get isOpen(){return null!==this._client&&this._client.isActive}}