@blocks-network/sdk 0.1.45

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

@@ -0,0 +1,133 @@
+/**
+ * Shared Stream Registry
+ *
+ * Instance-level map of active embedded and externally-coordinated streams.
+ * Named streams are ref-counted across tasks by a `taskIds: Set<string>`
+ * set — one entry per ref-holding task. Unnamed streams have a single
+ * taskId and are scoped to their task.
+ *
+ * Compatibility checks on named stream reuse:
+ * - direction must match
+ * - format must match
+ * - external flag must match
+ *
+ * First creator wins for: onActivate, transport tuning options, affinity.
+ * Duplicate onActivate callbacks for existing streams are silently ignored.
+ *
+ * `acquire()` is idempotent within a task: a second call with the same
+ * `(streamId, taskId)` returns `{ isNew: false, isNewForTask: false }`
+ * and does not grow the set. See SHARED_STREAM_LIFECYCLE_IMPL §Fix (e).
+ */
+import type { StreamClient } from '../stream/index.js';
+import type { StreamAffinity } from '../stream/descriptor.js';
+export interface StreamRegistryEntry {
+    streamId: string;
+    direction: 'outbound' | 'inbound' | 'bidirectional';
+    format: 'bytes' | 'events';
+    external: boolean;
+    /** Per-entry task tracking — the set of tasks that currently hold a ref. */
+    taskIds: Set<string>;
+    /** Affinity captured at first acquire (constant for the life of the entry). */
+    affinity: StreamAffinity;
+    streamClient: StreamClient | null;
+    activated: boolean;
+    /** The running onActivate promise, if any. */
+    activatePromise: Promise<void> | null;
+    /**
+     * First-acquirer setup promise. Installed synchronously on the entry
+     * before the first acquirer awaits `performStreamSetup`, resolved
+     * once `streamClient` is installed (or rejected if setup fails).
+     * Concurrent second acquirers on the same shared entry MUST await
+     * this promise before consulting `streamClient`; otherwise a race
+     * between first-acquirer setup and second-acquirer attach either
+     * throws "Stream exists but has no client" (Node) or silently creates
+     * a duplicate writer (Python). Null when setup is not in flight.
+     */
+    setupPromise: Promise<void> | null;
+    /**
+     * Derived reference count. Kept as a getter so existing callers /
+     * tests that inspect `entry.refCount` continue to work after the
+     * shape change (see SHARED_STREAM_LIFECYCLE_IMPL §Risk "Registry
+     * shape change ripples").
+     */
+    readonly refCount: number;
+}
+/** Result of an `acquire` call: distinguishes fresh entry / fresh-for-task / idempotent. */
+export interface AcquireResult {
+    entry: StreamRegistryEntry;
+    /** First time this entry was created (no prior ref-holders). */
+    isNew: boolean;
+    /**
+     * First time THIS task attached to the entry. True on new entries,
+     * true on existing entries when the taskId was not already tracked,
+     * false when the same task re-acquires idempotently.
+     */
+    isNewForTask: boolean;
+}
+interface AcquireOpts {
+    direction: 'outbound' | 'inbound' | 'bidirectional';
+    format: 'bytes' | 'events';
+    external: boolean;
+    affinity?: StreamAffinity;
+}
+export declare class StreamRegistry {
+    private readonly entries;
+    /**
+     * Get or create a registry entry for a stream.
+     *
+     * Three-case matrix (per SHARED_STREAM_LIFECYCLE_IMPL §Fix (e)):
+     *   1. Entry doesn't exist  -> create, taskIds = {taskId}, isNew: true,  isNewForTask: true
+     *   2. Entry exists + taskId already tracked -> idempotent no-op, isNew: false, isNewForTask: false
+     *   3. Entry exists + taskId is new          -> add to set,       isNew: false, isNewForTask: true
+     */
+    acquire(streamId: string, taskId: string, opts: AcquireOpts): AcquireResult;
+    /** Get a registry entry by stream ID. */
+    get(streamId: string): StreamRegistryEntry | undefined;
+    /**
+     * Release a task's reference to a stream.
+     *
+     * Pure bookkeeping: removes ``taskId`` from the entry's set and, on
+     * last-ref, removes the entry from the registry map. Does NOT tear
+     * down the underlying ``streamClient`` — callers snapshot the entry
+     * before this call (via ``get()``) and invoke ``streamClient.end()``
+     * themselves. This keeps the registry side-effect-free and lets
+     * agent-level teardown (logging, presence updates) live in one
+     * place. Matches the Python SDK's ``release()`` shape.
+     *
+     * Returns the remaining refCount (0 means the entry was removed).
+     */
+    release(streamId: string, taskId: string): number;
+    /**
+     * Force-remove a stream entry (for failStream).
+     *
+     * Deletes the entry from the registry and returns it. `taskIds` on
+     * the returned entry is LEFT INTACT so `failStream` can iterate the
+     * set of tasks to publish terminal failure to. The returned entry is
+     * disowned — `refCount` as exposed by the getter reflects the
+     * current size of the retained task set (the getter reads
+     * `taskIds.size` live, so a caller that mutates the set after
+     * removal sees the mutation), but no one can `release` it.
+     *
+     * DO NOT clear `taskIds` here "for hygiene": `failStream` reads the
+     * set to fan out `state: 'failed'` terminals, and Python's prior
+     * implementation silently broke that fan-out by clearing the set
+     * before returning. The single reader lives at
+     * `agent-instance.ts#failStreamImpl` — verify its loop still works
+     * before changing this behavior. See QUESTIONS.md R6
+     * (shared_stream_lifecycle).
+     */
+    forceRemove(streamId: string): StreamRegistryEntry | undefined;
+    /**
+     * Release all streams for a given task.
+     * Returns entries whose refCount reached 0 (removed from registry).
+     * Callers should end() the streamClient on each returned entry.
+     */
+    releaseAllForTask(taskId: string): StreamRegistryEntry[];
+    /** Count of active embedded stream processing contexts. */
+    get activeStreamCount(): number;
+    /** All stream IDs in the registry. */
+    streamIds(): string[];
+    /** Clear the entire registry. */
+    clear(): void;
+}
+export {};

package/dist/runtime/stream-registry.js

@@ -0,0 +1 @@
+export class StreamRegistry{constructor(){this.entries=new Map}acquire(e,t,r){const i=this.entries.get(e);if(i){if(i.external!==r.external)throw new Error(`Stream "${e}" incompatible: cannot mix embedded and external`);if(i.direction!==r.direction)throw new Error(`Stream "${e}" incompatible: direction mismatch (existing: ${i.direction}, requested: ${r.direction})`);if(i.format!==r.format)throw new Error(`Stream "${e}" incompatible: format mismatch (existing: ${i.format}, requested: ${r.format})`);const s=r.affinity??"dedicated";if(i.affinity!==s)throw new Error(`Stream "${e}" incompatible: affinity mismatch (existing: ${i.affinity}, requested: ${s})`);return i.taskIds.has(t)?{entry:i,isNew:!1,isNewForTask:!1}:(i.taskIds.add(t),{entry:i,isNew:!1,isNewForTask:!0})}const s=function(e,t,r){const i=new Set([t]);return{streamId:e,direction:r.direction,format:r.format,external:r.external,taskIds:i,affinity:r.affinity??"dedicated",streamClient:null,activated:!1,activatePromise:null,setupPromise:null,get refCount(){return i.size}}}(e,t,r);return this.entries.set(e,s),{entry:s,isNew:!0,isNewForTask:!0}}get(e){return this.entries.get(e)}release(e,t){const r=this.entries.get(e);return r?(r.taskIds.delete(t),0===r.taskIds.size?(this.entries.delete(e),0):r.taskIds.size):0}forceRemove(e){const t=this.entries.get(e);return t&&this.entries.delete(e),t}releaseAllForTask(e){const t=[];for(const[r,i]of this.entries)i.taskIds.has(e)&&(i.taskIds.delete(e),0===i.taskIds.size&&(this.entries.delete(r),t.push(i)));return t}get activeStreamCount(){let e=0;for(const t of this.entries.values())t.external||e++;return e}streamIds(){return[...this.entries.keys()]}clear(){this.entries.clear()}}

package/dist/runtime/stream-setup-helper.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Stream Setup Helper - T7a abort-payload parsing
+ *
+ * Internal helper for consuming the streamSetup Function's response.
+ * The streamSetup Function returns T7a via request.abort(customPayload),
+ * which the PubNub SDK surfaces as a 403 error. This helper extracts
+ * the T7a token from the error body after verifying the expected markers.
+ *
+ * This is a protocol-consumption helper only. It does not implement the
+ * full stream setup handshake (that belongs to Phase 3 SDK runtime).
+ *
+ * The stream setup protocol is documented in the SDK contract and event flow docs.
+ */
+/**
+ * Parsed stream setup response extracted from the abort payload.
+ */
+export interface StreamSetupResult {
+    taskId: string;
+    streamId: string;
+    channel: string;
+    direction: 'outbound' | 'inbound' | 'bidirectional';
+    phase: 'embedded' | 'token_request' | 'activate';
+    token?: string;
+    tokenTtlMinutes: number;
+}
+/**
+ * Structured error returned by the streamSetup Function for validation
+ * failures. The Function returns { ok: false, error: { code, message } }
+ * via request.abort(), which is also surfaced as a 403 error. This type
+ * lets callers distinguish a server-side validation rejection from an
+ * opaque PubNub 403.
+ */
+export interface StreamSetupError {
+    code: string;
+    message: string;
+}
+/**
+ * Attempt to extract a structured error from a PubNub publish error.
+ *
+ * When the streamSetup Function rejects a request (e.g., missing
+ * durationMinutes, invalid direction), it returns
+ * { ok: false, error: { code, message } } via request.abort().
+ * This is surfaced as a 403 by the PubNub SDK, just like the success
+ * path. This function extracts the structured error from the 403 body.
+ *
+ * Returns null if the error is not a structured setup error (i.e., it is
+ * either a real 403 or a success abort payload).
+ *
+ * @param error - The error object thrown by pubnub.publish()
+ * @returns The parsed StreamSetupError, or null
+ */
+export declare function parseStreamSetupError(error: unknown): StreamSetupError | null;
+/**
+ * Attempt to parse a T7a stream setup response from a PubNub publish error.
+ *
+ * The streamSetup Function calls request.abort(customPayload), which causes
+ * the PubNub SDK to reject the publish with a PubNubError. The error
+ * object contains the custom payload at:
+ *   error.status.errorData.message  (already parsed by the Node SDK)
+ *
+ * This function checks the marker fields (ok: true, streamSetupResponse)
+ * and extracts the result. Returns null if the error is not a valid
+ * stream setup response (i.e., it is a real 403 error).
+ *
+ * @param error - The error object thrown by pubnub.publish()
+ * @returns The parsed StreamSetupResult, or null if not a valid setup response
+ */
+export declare function parseStreamSetupResponse(error: unknown): StreamSetupResult | null;
+/**
+ * Extract a structured error from a raw abort payload object.
+ * The streamSetup Function returns { ok: false, error: { code, message } }
+ * for validation failures (missing fields, invalid direction, invalid
+ * durationMinutes, etc.). This function checks for that shape and
+ * returns the error details, or null if the payload is not a structured error.
+ *
+ * @param payload - The parsed abort payload
+ * @returns The parsed StreamSetupError, or null if not an error payload
+ */
+export declare function extractErrorFromPayload(payload: unknown): StreamSetupError | null;
+/**
+ * Extract StreamSetupResult from a raw abort payload object.
+ * Validates the marker fields and required properties.
+ *
+ * @param payload - The parsed abort payload
+ * @returns The parsed StreamSetupResult, or null if invalid
+ */
+export declare function extractFromPayload(payload: unknown): StreamSetupResult | null;

package/dist/runtime/stream-setup-helper.js

@@ -0,0 +1 @@
+const t=["outbound","inbound","bidirectional"],e=["embedded","token_request","activate"];export function parseStreamSetupError(t){if(!t||"object"!=typeof t)return null;const e=t.status;if(!e)return null;if(403!==(e.statusCode??e.category))return null;const n=e.errorData;if(!n)return null;const r=n.message;return r&&"object"==typeof r?extractErrorFromPayload(r):null}export function parseStreamSetupResponse(t){if(!t||"object"!=typeof t)return null;const e=t.status;if(!e)return null;if(403!==(e.statusCode??e.category))return null;const n=e.errorData;if(!n)return null;const r=n.message;return r&&"object"==typeof r?extractFromPayload(r):null}export function extractErrorFromPayload(t){if(!t||"object"!=typeof t)return null;const e=t;if(!1!==e.ok)return null;const n=e.error;if(!n||"object"!=typeof n)return null;const r=n,o=r.code,u=r.message;return"string"==typeof o&&o&&"string"==typeof u&&u?{code:o,message:u}:null}export function extractFromPayload(n){if(!n||"object"!=typeof n)return null;const r=n;if(!0!==r.ok)return null;const o=r.streamSetupResponse;if(!o||"object"!=typeof o)return null;const u=o,l=u.taskId,s=u.streamId,i=u.channel,a=u.direction,c=u.phase,f=u.tokenTtlMinutes;if("string"!=typeof l||!l)return null;if("string"!=typeof s||!s)return null;if("string"!=typeof i||!i)return null;if("string"!=typeof a||!t.includes(a))return null;if("string"!=typeof c||!e.includes(c))return null;if("number"!=typeof f||f<=0)return null;const p={taskId:l,streamId:s,channel:i,direction:a,phase:c,tokenTtlMinutes:f},y=u.token;return"string"==typeof y&&y.length>0&&(p.token=y),p}

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

@@ -0,0 +1,259 @@
+/**
+ * TaskClient -- send tasks to other agents via the PubNub Functions RPC gateway.
+ *
+ * Provides:
+ * - `sendMessage()` -- calls JSON-RPC "SendMessage" and returns a TaskSession with eager subscription
+ * - `connect()` -- connect to an existing task and return a pre-populated TaskSession
+ * - `create()` -- static factory to build a TaskClient from env vars or CDM config
+ * - Task lifecycle methods: getTask, listTasks, cancelTask, pauseTask, resumeTask, retryTask, terminateTask
+ * - `subscribeToTask()` -- low-level subscribe to real-time task events via PubNub channels
+ */
+import PubNub from 'pubnub';
+import { TaskSession, type CallbackErrorContext } from './task-session.js';
+import type { AgentAuth } from './agent-auth.js';
+import type { AuthProvider } from './auth-provider.js';
+import { type TokenResult, type TokenEndpointConfig } from './consumer-auth.js';
+import { type AgentCard } from './agent-registry.js';
+export interface TaskClientOptions {
+    subscribeKey: string;
+    publishKey?: string;
+    /** Internal/advanced hook for supplying an auth provider directly. */
+    authProvider?: AuthProvider;
+    /** Shared PubNub instance for low-level subscribeToTask() operations. */
+    pubnub?: PubNub;
+    /** Shared factory for low-level subscribeToTask(). Creates once, caches. */
+    createPubNub?: () => PubNub;
+    /**
+     * Per-session factory for sendMessage() -> TaskSession eager subscriptions.
+     * Must return a fresh PubNub client per call so each session gets its own
+     * token-isolated instance. Not used by subscribeToTask().
+     */
+    createSessionPubNub?: () => PubNub;
+    defaultOwnerId?: string;
+    baseUrl?: string;
+    /** AgentAuth instance for API key-based authentication */
+    agentAuth?: AgentAuth;
+}
+/**
+ * A request part item. Each part may include a `partId` referencing a
+ * declared input in the agent's io.inputs[].id.
+ * Explicit optional fields match the agent-instance RequestPart for consistency.
+ *
+ * For file inputs: set `file` (raw data) and `fileName`. The SDK
+ * automatically inlines small files (<= 16 KB) or runs the pre-signed
+ * URL upload flow for large files.
+ */
+export interface SendMessageRequestPart {
+    partId?: string;
+    text?: string;
+    contentType?: string;
+    /** Raw file data. Small files (<= 16 KB) are inlined as base64;
+     *  large files use the pre-signed URL upload flow. Accepts
+     *  `Uint8Array`, `ArrayBuffer`, `Blob`, or `File` -- browser
+     *  consumers can pass a `File` from `<input type="file">` directly. */
+    file?: Uint8Array | ArrayBuffer | Blob | File;
+    /** Original file name. Required when `file` is provided. */
+    fileName?: string;
+    [key: string]: unknown;
+}
+export interface SendMessageParams {
+    agentName: string;
+    requestParts: SendMessageRequestPart[];
+    /** Optional idempotency key for duplicate detection. Scoped to the caller's identity. */
+    idempotencyKey?: string;
+    ownerId?: string;
+    /** Task kind. Defaults to request when omitted. */
+    taskKind?: 'request' | 'pipe';
+    /** Duration in minutes. Required for pipe tasks. */
+    duration?: number;
+    /** Consumer's public key for E2E encryption. Included in extensions.blocks. */
+    consumerPublicKey?: string;
+    pushNotificationConfig?: {
+        url: string;
+        filter?: string;
+        authStrategy?: string;
+    };
+    retryPolicy?: {
+        maxRetries?: number;
+        expiresAfterSec?: number;
+    };
+    /** Enable auto-drain on terminal (default: true). When true, TaskSession
+     *  waits for open streams to drain via stream_end before closing. When
+     *  false, terminal causes immediate close with no stream force-end. */
+    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;
+}
+export interface TaskInfo {
+    taskId: string;
+    agentName?: string;
+    owner?: string;
+    state?: string;
+    createdTime?: string;
+    updatedTime?: string;
+    [key: string]: unknown;
+}
+export interface ListTasksParams {
+    ownerId?: string;
+    agentName?: string;
+    state?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface ListTasksResult {
+    tasks: TaskInfo[];
+    next?: string;
+    totalCount?: number;
+}
+export interface TaskEvent {
+    type: string;
+    taskId: string;
+    [key: string]: unknown;
+}
+export interface TaskEventCallbacks {
+    /** Progress events (type: "progress") */
+    onProgress?: (event: TaskEvent) => void;
+    /** Artifact events (type: "artifact") */
+    onArtifact?: (event: TaskEvent) => void;
+    /** Terminal events (type: "terminal") -- task completed, failed, or canceled */
+    onTerminal?: (event: TaskEvent) => void;
+    /** System events (type: "system") -- paused, resumed, etc. */
+    onSystem?: (event: TaskEvent) => void;
+    /** Catch-all for any event */
+    onEvent?: (event: TaskEvent) => void;
+    /** Error handler for callback exceptions (P1-3) */
+    onError?: (error: Error, context: CallbackErrorContext) => void;
+}
+export interface TaskSubscription {
+    unsubscribe(): void;
+}
+export declare class TaskClient {
+    private readonly config;
+    private _pubnub?;
+    private readonly _createPubNub?;
+    private readonly _createSessionPubNub?;
+    private readonly defaultOwnerId?;
+    private readonly _ownsPubNub;
+    private _subscribeKey;
+    private _publishKey;
+    private _consumerAuth?;
+    constructor(options: TaskClientOptions);
+    /**
+     * Create a TaskClient from environment variables or CDM config.
+     *
+     * Resolution order for each config value:
+     * - Explicit options (if provided)
+     * - Environment variables (BLOCKS_*)
+     * - CDM config (fetched from cdmUrl or BLOCKS_CDM_URL)
+     *
+     * `listing` is required -- it determines which CDM keyset to use:
+     * - 'playground' selects the CDM playground keyset
+     * - 'private' or 'public' selects the CDM network keyset
+     */
+    static create(options?: {
+        listing?: 'playground' | 'private' | 'public';
+        cdmUrl?: string;
+        subscribeKey?: string;
+        publishKey?: string;
+        baseUrl?: string;
+        apiKey?: string;
+        tokenEndpoint?: TokenEndpointConfig;
+        tokenProvider?: () => Promise<TokenResult>;
+        onAuthError?: (error: Error) => void;
+    }): Promise<TaskClient>;
+    /** Returns the authenticated user ID from ConsumerAuth, or null. */
+    getUserId(): string | null;
+    /**
+     * Look up an agent's card by name from the registry.
+     * Returns null if the agent is not found or has no card.
+     */
+    getAgentCard(agentName: string): Promise<AgentCard | null>;
+    /**
+     * Update keyset keys after an environment switch.
+     * Updates both the RPC config and the keys used for PubNub client creation.
+     */
+    updateKeys(subscribeKey: string, publishKey?: string): void;
+    /**
+     * Lazily resolve the PubNub instance for subscribe operations.
+     * If a direct `pubnub` was provided, use it. Otherwise, call the factory.
+     */
+    private getPubNub;
+    /**
+     * Clean up the PubNub instance if it was created by this TaskClient (via createPubNub factory).
+     * Externally-provided instances are left untouched.
+     * Stops ConsumerAuth refresh timer if active. Token remains readable
+     * so active sessions can still call cancel/terminate using the stale token.
+     */
+    destroy(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Create a per-session PubNub subscribe client with the given T4 token.
+     * Each TaskSession gets its own client to prevent token stomping.
+     *
+     * Uses the dedicated `createSessionPubNub` factory when available.
+     * Falls back to an internal fresh-client construction otherwise.
+     * Never uses the shared `createPubNub` factory -- that is reserved
+     * for low-level `subscribeToTask()` operations.
+     */
+    private createPerSessionPubNub;
+    private fetchConsumerReadToken;
+    /**
+     * Send a message (task) to an agent via JSON-RPC "SendMessage".
+     * Returns a TaskSession that eagerly subscribes to the task channel.
+     *
+     * When request parts include `file` data:
+     * - Small files (<= 16 KB): inlined as base64 artifactRef on the part
+     * - Large files (> 16 KB): uploaded via pre-signed URL flow, then
+     *   SendMessage includes the uploadSessionId to bind files to the task
+     */
+    sendMessage(params: SendMessageParams): Promise<TaskSession>;
+    /**
+     * Connect to an existing task. Returns a TaskSession pre-populated
+     * with stream refs, artifact refs, and task state from history.
+     *
+     * For active tasks: the session subscribes to the task channel and
+     * live events flow through callbacks from that point forward.
+     *
+     * For terminal tasks: the session is pre-populated but does not
+     * subscribe. The consumer reads listArtifacts(), listStreams(), and
+     * session.state, then calls close().
+     *
+     * Uses the task-read-token endpoint with role:'consumer' to acquire
+     * a fresh T4 read token. The caller does not need to persist or
+     * supply readToken, orgId, ownerId, or agentName.
+     */
+    connect(params: {
+        taskId: 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;
+    }): Promise<TaskSession>;
+    getTask(taskId: string): Promise<TaskInfo>;
+    listTasks(params?: ListTasksParams): Promise<ListTasksResult>;
+    cancelTask(taskId: string): Promise<void>;
+    pauseTask(taskId: string): Promise<void>;
+    resumeTask(taskId: string): Promise<void>;
+    retryTask(taskId: string): Promise<void>;
+    terminateTask(taskId: string): Promise<void>;
+    /**
+     * Subscribe to real-time task events via PubNub.
+     * Requires pubnub instance in TaskClientOptions.
+     */
+    subscribeToTask(taskId: string, orgId: string, callbacks: TaskEventCallbacks): TaskSubscription;
+}

package/dist/runtime/task-client.js

@@ -0,0 +1 @@
+import e from"pubnub";import{callRpc as t}from"./rpc-client.js";import{taskChannel as s}from"./channel-manager.js";import{TaskSession as n}from"./task-session.js";import{ConsumerAuth as i}from"./consumer-auth.js";import{shouldInlineArtifact as r,buildArtifactRef as o}from"./artifacts.js";import{uploadFile as a}from"./file-upload.js";import{normalizeFileInput as c}from"./file-input.js";import{fetchCdmConfig as u}from"./cdm-config.js";import{captureAffinity as b,injectAffinity as d}from"./write-affinity.js";import{getEnv as l}from"../env.js";import{StreamRef as h}from"./stream-ref.js";import{invertDirection as f}from"../stream/index.js";import{asPubNubFetcher as p}from"./pubnub-types.js";import{CURRENT_PROTOCOL_VERSION as m,PROTOCOL_VERSION_HEADER as y}from"./protocol-version.js";import{getAgent as k}from"./agent-registry.js";const g=new Set(["completed","failed","canceled"]);export class TaskClient{constructor(e){this._ownsPubNub=!1,this.config={subscribeKey:e.subscribeKey,authProvider:e.authProvider,baseUrl:e.baseUrl,agentAuth:e.agentAuth},this._pubnub=e.pubnub,this._createPubNub=e.createPubNub,this._createSessionPubNub=e.createSessionPubNub,this.defaultOwnerId=e.defaultOwnerId,this._subscribeKey=e.subscribeKey,this._publishKey=e.publishKey??"",this._ownsPubNub=!e.pubnub&&!!e.createPubNub}static async create(t){const s=t??{},n=s.listing;if(!n)throw new Error("TaskClient.create() requires a listing option ('playground', 'private', or 'public') to select the CDM keyset.");const r=!!(s.apiKey||s.tokenEndpoint||s.tokenProvider);if([s.apiKey,s.tokenEndpoint,s.tokenProvider].filter(Boolean).length>1)throw new Error("Only one token provider mode may be specified");const o=s.cdmUrl??l("BLOCKS_CDM_URL"),a=await u(o),c="playground"===n?a.playground:a.network,b=s.subscribeKey??l("BLOCKS_SUBSCRIBE_KEY")??c.subscribeKey,d=s.publishKey??l("BLOCKS_PUBLISH_KEY")??c.publishKey,h=s.baseUrl??l("BLOCKS_BACKEND_URL")??a.api.baseUrl;if(!b)throw new Error("TaskClient.create() could not resolve subscribeKey from options, env, or CDM");if(!h)throw new Error("TaskClient.create() could not resolve baseUrl. Set baseUrl option, BLOCKS_BACKEND_URL env var, or ensure CDM config has api.baseUrl.");const f=()=>{const t=`blocks-task-${Date.now().toString(36)}-${Math.random().toString(36).slice(2,6)}`;return new e({subscribeKey:b,publishKey:d||void 0,userId:t,enableEventEngine:!0})};if(r){const e=new i({apiKey:s.apiKey,tokenEndpoint:s.tokenEndpoint,tokenProvider:s.tokenProvider,baseUrl:h,onAuthError:s.onAuthError});await e.init();const t=new TaskClient({subscribeKey:b,publishKey:d,baseUrl:h,createSessionPubNub:f,defaultOwnerId:e.getUserId()??void 0});return t.config.authProvider=e,t._consumerAuth=e,t}return new TaskClient({subscribeKey:b,publishKey:d,baseUrl:h,createSessionPubNub:f})}getUserId(){return this._consumerAuth?.getUserId()??null}async getAgentCard(e){const t=await k(e,{baseUrl:this.config.baseUrl});return t?.card??null}updateKeys(e,t){this.config.subscribeKey=e,this._subscribeKey=e,this._publishKey=t??""}getPubNub(){if(!this._pubnub&&this._createPubNub&&(this._pubnub=this._createPubNub()),!this._pubnub)throw new Error("TaskClient requires a pubnub instance for subscribe. Pass pubnub or createPubNub in TaskClientOptions.");return this._pubnub}destroy(){this._pubnub&&this._ownsPubNub&&(this._pubnub.destroy(),this._pubnub=void 0),this._consumerAuth&&this._consumerAuth.destroy()}[Symbol.dispose](){this.destroy()}createPerSessionPubNub(t){let s;if(this._createSessionPubNub)s=this._createSessionPubNub();else{const t=`blocks-task-${Date.now().toString(36)}-${Math.random().toString(36).slice(2,6)}`;s=new e({subscribeKey:this._subscribeKey,publishKey:this._publishKey||void 0,userId:t,enableEventEngine:!0})}return t&&s.setToken(t),s}async fetchConsumerReadToken(e){if(!this.config.baseUrl)throw new Error("connect() requires a backend baseUrl. Set baseUrl in TaskClientOptions.");const t=`${this.config.baseUrl.replace(/\/+$/,"")}/api/v1/auth/task-read-token`,s=async()=>{const s={"Content-Type":"application/json",[y]:m},n=this.config.authProvider?.getAuthHeader();return n&&(s.Authorization=n),d(s),fetch(t,{method:"POST",headers:s,body:JSON.stringify({taskId:e,role:"consumer"})})};let n=await s();if(b(n.headers),401===n.status&&this.config.authProvider){await this.config.authProvider.onAuthFailure()&&(n=await s(),b(n.headers))}if(!n.ok){const e=await n.text().catch(()=>"");throw new Error(`task-read-token failed: HTTP ${n.status}${e?` ${e}`:""}`)}return n.json()}async sendMessage(e){const s=e.ownerId||this.defaultOwnerId||"",i=e.taskKind,u=e.duration;if("pipe"===i){if(null==u||!Number.isInteger(u)||u<1||u>43200)throw new Error("Pipe tasks require a duration between 1 and 43200 minutes")}else if(null!=u)throw new Error("Request tasks must not include a duration. Duration is only valid for pipe tasks.");let b;const d=[];for(const t of e.requestParts)if(t.file){if(!t.partId)throw new Error("partId is required for file-bearing request parts");const s=c(t.file),n=t.fileName??"unnamed",i=t.contentType??"application/octet-stream";if(r(s.size)){const e=await s.getBytes(),r=o({data:e,mimeType:i,fileName:n}),{file:a,fileName:c,text:u,...b}=t;d.push({...b,artifactRef:r})}else{if(!this.config.baseUrl)throw new Error("File upload requires a backend baseUrl. Set baseUrl in TaskClientOptions.");const r={baseUrl:this.config.baseUrl,authProvider:this.config.authProvider,agentAuth:this.config.agentAuth},o={role:"consumer-input",agentName:e.agentName,fileName:n,fileSize:s.size,mimeType:i,partId:t.partId,uploadSessionId:b},c=await a(r,o,s.uploadBody);c.uploadSessionId&&(b=c.uploadSessionId);const{file:u,fileName:l,...h}=t;d.push({partId:h.partId})}}else{const{file:e,fileName:s,...n}=t;d.push(n)}const l={agentName:e.agentName,requestParts:d};b&&(l.uploadSessionId=b),e.idempotencyKey&&(l.idempotencyKey=e.idempotencyKey),l.ownerId=s;const h={};i&&(h.taskKind=i),null!=u&&(h.duration=u),e.consumerPublicKey&&(h.consumerPublicKey=e.consumerPublicKey),Object.keys(h).length>0&&(l.extensions={blocks:h}),e.pushNotificationConfig&&(l.pushNotificationConfig=e.pushNotificationConfig),e.retryPolicy&&(l.retryPolicy=e.retryPolicy);const f=await t(this.config,"SendMessage",l),p=f.extensions?.blocks,m=p?.readToken??null,y=p?.streamChannels?.status??void 0;if(!0===f.idempotent&&!!f.state&&g.has(f.state))return new n({taskId:f.taskId,ownerId:s,orgId:f.orgId??s,readToken:m,statusChannel:y,agentName:e.agentName,pubnub:null,ownsSubscribeClient:!1,sdkOptions:{subscribeKey:this._subscribeKey,publishKey:this._publishKey},rpcConfig:this.config,idempotent:f.idempotent,queued:f.queued,pushConfigId:f.pushConfigId,preClosed:!0,state:f.state});const k=this.createPerSessionPubNub(m);return new n({taskId:f.taskId,ownerId:s,orgId:f.orgId??s,readToken:m,statusChannel:y,agentName:e.agentName,pubnub:k,ownsSubscribeClient:!0,sdkOptions:{subscribeKey:this._subscribeKey,publishKey:this._publishKey},rpcConfig:this.config,idempotent:f.idempotent,queued:f.queued,pushConfigId:f.pushConfigId,autoDrain:e.autoDrain,drainWindowMs:e.drainWindowMs})}async connect(e){const{taskId:t}=e;if(!this.config.authProvider?.getAuthHeader())throw new Error("connect() requires an authenticated TaskClient. Use apiKey, tokenEndpoint, or tokenProvider. AgentAuth is not supported for consumer task connections.");const s=await this.getTask(t);if(!s)throw new Error(`Task not found: ${t}`);const i=s.agentName??"",r=s.state??"",o=await this.fetchConsumerReadToken(t),{pamToken:a,channel:c}=o,u={subscribeKey:this._subscribeKey,publishKey:this._publishKey},b=this.createPerSessionPubNub(a);try{const o=await b.time(),d=String(o.timetoken),l=p(b);let m,y=new Map,k=[],w="0";if(l?.fetchMessages){const e=await async function(e,t){const s=[];let n;for(;;){const i={channels:[t],count:100};n&&(i.start=n);const r=await e.fetchMessages(i),o=r.channels?.[t]??[];if(0===o.length)break;if(s.push(...o),o.length<100)break;n=o[0].timetoken}return s.sort((e,t)=>e.timetoken<t.timetoken?-1:e.timetoken>t.timetoken?1:0),s}(l,c),s=function(e,t,s,n){const i=new Map,r=[];let o,a="0",c="0";for(const u of e){u.timetoken&&u.timetoken>a&&(a=u.timetoken);const e=u.message;if(e&&"object"==typeof e&&e.type){if("terminal"===e.type){const t=String(u.timetoken??"0");if(t>=c){const s=e.state;"completed"!==s&&"failed"!==s&&"canceled"!==s||(o=s,c=t)}}if("progress"===e.type&&"stream_started"===e.streamEvent&&e.streams){const r=e.declaredStream,o=e.streams;for(const[e,a]of Object.entries(o)){if(!a||"object"!=typeof a||i.has(e))continue;const o=a.direction,c=f(o),u=a.format;if(!u||"bytes"!==u&&"events"!==u)continue;const b=a.affinity;if("dedicated"!==b&&"shared"!==b){console.warn(`[TaskClient] history-preload: dropping stream "${e}" for task "${t}" — invalid or missing affinity (got ${JSON.stringify(a.affinity)})`);continue}const d={taskId:t,streamId:e,agentName:s,channel:a.channel,token:a.token,agentDirection:o,localDirection:c,format:u,affinity:b,metadata:a.metadata,declaredStream:r};i.set(e,new h(d,n))}}if("artifact"===e.type&&e.artifactRef){const t=e.artifactRef;t&&"object"==typeof t&&t.kind&&r.push(t)}}}return{streams:i,artifacts:r,highWaterMark:a,terminalState:o}}(e,t,i,u);y=s.streams,k=s.artifacts,w=s.highWaterMark,m=s.terminalState}const K=m&&g.has(m)?m:r;if(g.has(K))return new n({taskId:t,ownerId:s.owner??"",readToken:a,statusChannel:c,agentName:i,pubnub:b,ownsSubscribeClient:!0,sdkOptions:u,rpcConfig:this.config,autoDrain:e.autoDrain,drainWindowMs:e.drainWindowMs,state:K,skipSubscription:!0,preloadedStreams:y,preloadedArtifacts:k});const P="0"!==w?w:d,T=[];let S,I=!1;const C={message:e=>{if(e.channel!==c)return;const t=e.message;if(!t||"object"!=typeof t||!t.type)return;const s=String(e.timetoken??"0");I&&S?S(t,s):T.push({message:t,timetoken:s})}};b.addListener(C),b.subscribe({channels:[c],timetoken:P});const N=new n({taskId:t,ownerId:s.owner??"",readToken:a,statusChannel:c,agentName:i,pubnub:b,ownsSubscribeClient:!0,sdkOptions:u,rpcConfig:this.config,autoDrain:e.autoDrain,drainWindowMs:e.drainWindowMs,state:r,preloadedStreams:y,preloadedArtifacts:k,externalSubscription:{listener:C,channel:c,onReady:e=>{S=e}}});if(S){const e=S;for(const t of T)t.timetoken>P&&e(t.message,t.timetoken)}return T.length=0,I=!0,N}catch(e){throw b.destroy(),e}}async getTask(e){return(await t(this.config,"GetTask",{taskId:e})).task}async listTasks(e){return t(this.config,"ListTasks",{...e})}async cancelTask(e){await t(this.config,"CancelTask",{taskId:e})}async pauseTask(e){await t(this.config,"PauseTask",{taskId:e})}async resumeTask(e){await t(this.config,"ResumeTask",{taskId:e})}async retryTask(e){await t(this.config,"RetryTask",{taskId:e})}async terminateTask(e){await t(this.config,"TerminateTask",{taskId:e})}subscribeToTask(e,t,n){return function(e,t,n,i){const r=s(t,n),o={message:e=>{if(e.channel!==r)return;const t=e.message;if(t&&"object"==typeof t&&t.type){if(i.onEvent)try{i.onEvent(t)}catch(e){w(e,"onEvent",t,i.onError)}switch(t.type){case"progress":if(i.onProgress)try{i.onProgress(t)}catch(e){w(e,"onProgress",t,i.onError)}break;case"artifact":if(i.onArtifact)try{i.onArtifact(t)}catch(e){w(e,"onArtifact",t,i.onError)}break;case"terminal":if(i.onTerminal)try{i.onTerminal(t)}catch(e){w(e,"onTerminal",t,i.onError)}break;case"system":if(i.onSystem)try{i.onSystem(t)}catch(e){w(e,"onSystem",t,i.onError)}}}}};return e.addListener(o),e.subscribe({channels:[r],timetoken:1e3}),{unsubscribe(){e.removeListener(o),e.unsubscribe({channels:[r]})}}}(this.getPubNub(),e,t,n)}}function w(e,t,s,n){const i=e instanceof Error?e:new Error(String(e));if(n)try{n(i,{entryPoint:"subscribeToTask",callbackType:t,event:s})}catch{}else console.warn(`[subscribeToTask] callback error in ${t}:`,i.message)}