@blocks-network/sdk 0.1.45

package/dist/defaults.d.ts

@@ -0,0 +1,7 @@
+export declare const DEFAULTS: {
+    cdmUrl: string;
+    inlineLimitBytes: number;
+    maxUploadBytes: number;
+    concurrency: number;
+    expectedInstances: number;
+};

package/dist/defaults.js

@@ -0,0 +1 @@
+import{DEFAULT_CDM_URL as e}from"./runtime/cdm-config.js";export const DEFAULTS={cdmUrl:e,inlineLimitBytes:16384,maxUploadBytes:26214400,concurrency:1,expectedInstances:1};

package/dist/env.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Read an environment variable, returning undefined in non-Node
+ * environments (browsers, edge runtimes) where process is unavailable.
+ */
+export declare function getEnv(key: string): string | undefined;

package/dist/env.js

@@ -0,0 +1 @@
+export function getEnv(e){if("undefined"!=typeof process&&process.env)return process.env[e]}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export { startAgentInstance } from './runtime/agent-instance.js';
+export type { ArtifactEntry, HandlerFn, HandlerResult, RequestPart, StartTaskMessage, ExpireTaskMessage, TaskContext, CreateStreamOptions, AgentInstanceOptions, AgentInstancePresenceState, AgentInstanceHandle, } from './runtime/agent-instance.js';
+export type { StreamObject, OnActivateCallback } from './runtime/stream-context.js';
+export type { AgentCard, OutputAgentCard, AgentSkill } from './runtime/agent-registry.js';
+export { createPubNubClient, type PubNubClientConfig } from './runtime/pubnub-client.js';
+export { createChannelManager, ChannelManager, streamChannel } from './runtime/channel-manager.js';
+export { buildArtifactRef, shouldInlineArtifact, decodeInlineArtifact, downloadArtifact, type ArtifactRef, type DownloadedArtifact, } from './runtime/artifacts.js';
+export { connectAgent, fetchAgentRegistry, getAgent, removeAgent, fetchAgentsBySkill, fetchAgentsByListing, type AgentRegistryResult, } from './runtime/agent-registry.js';
+export { DEFAULTS } from './defaults.js';
+/** Platform-wide upload ceiling (bytes). Mirrors afui_mvp_backend MAX_FILE_SIZE_BYTES. */
+export declare const BLOCKS_MAX_UPLOAD_BYTES: number;
+export { loadBlocksConfig, type BlocksConfig } from './config-loader.js';
+export { TaskClient } from './runtime/task-client.js';
+export type { TaskClientOptions, SendMessageParams, SendMessageRequestPart, TaskInfo, ListTasksParams, ListTasksResult, TaskEvent as TaskClientEvent, TaskEventCallbacks, TaskSubscription, } from './runtime/task-client.js';
+export { TaskSession } from './runtime/task-session.js';
+export type { TaskEvent, ProgressEvent, ArtifactEvent, TerminalEvent, Unsubscribe, CallbackErrorContext, } from './runtime/task-session.js';
+export { textPart, filePart, filePartFromPath } from './runtime/part-helpers.js';
+export { StreamRef, StreamUnavailableError } from './runtime/stream-ref.js';
+export type { StreamDescriptor } from './runtime/stream-ref.js';
+export { AgentAuth, AgentAuthFatalError } from './runtime/agent-auth.js';
+export type { RegistrationPayload, RegistrationResult } from './runtime/agent-auth.js';
+export type { AuthProvider } from './runtime/auth-provider.js';
+export { ConsumerAuth } from './runtime/consumer-auth.js';
+export type { ConsumerAuthOptions, TokenEndpointConfig, TokenEndpointCredentials, TokenResult, } from './runtime/consumer-auth.js';
+export { StreamRegistry } from './runtime/stream-registry.js';
+export { CredentialCache } from './runtime/credential-cache.js';
+export { fetchCdmConfig, DEFAULT_CDM_URL } from './runtime/cdm-config.js';
+export type { CdmConfig, CdmKeyset, CdmApiConfig } from './runtime/cdm-config.js';

package/dist/index.js

@@ -0,0 +1 @@
+export{startAgentInstance}from"./runtime/agent-instance.js";export{createPubNubClient}from"./runtime/pubnub-client.js";export{createChannelManager,ChannelManager,streamChannel}from"./runtime/channel-manager.js";export{buildArtifactRef,shouldInlineArtifact,decodeInlineArtifact,downloadArtifact}from"./runtime/artifacts.js";export{connectAgent,fetchAgentRegistry,getAgent,removeAgent,fetchAgentsBySkill,fetchAgentsByListing}from"./runtime/agent-registry.js";export{DEFAULTS}from"./defaults.js";import{DEFAULTS as e}from"./defaults.js";export const BLOCKS_MAX_UPLOAD_BYTES=e.maxUploadBytes;export{loadBlocksConfig}from"./config-loader.js";export{TaskClient}from"./runtime/task-client.js";export{TaskSession}from"./runtime/task-session.js";export{textPart,filePart,filePartFromPath}from"./runtime/part-helpers.js";export{StreamRef,StreamUnavailableError}from"./runtime/stream-ref.js";export{AgentAuth,AgentAuthFatalError}from"./runtime/agent-auth.js";export{ConsumerAuth}from"./runtime/consumer-auth.js";export{StreamRegistry}from"./runtime/stream-registry.js";export{CredentialCache}from"./runtime/credential-cache.js";export{fetchCdmConfig,DEFAULT_CDM_URL}from"./runtime/cdm-config.js";

package/dist/runtime/agent-auth.d.ts

@@ -0,0 +1,94 @@
+/**
+ * AgentAuth — API key-based authentication for agent instances.
+ *
+ * Authenticates by connecting the agent via POST /api/v1/auth/agent/connect
+ * with the API key in the Bearer header. The connect response includes
+ * a short-lived JWT and refresh token. Handles transparent token refresh
+ * with Promise-based mutex to prevent concurrent refresh requests, and
+ * provides authenticatedFetch() for automatic 401 retry.
+ *
+ * On refresh token invalidation, re-connects using the stored connect
+ * payload (idempotent).
+ */
+/**
+ * Connect payload sent to POST /api/v1/auth/agent/connect.
+ * Contains instance-specific fields needed for runtime credential issuance.
+ */
+export interface RegistrationPayload {
+    agentName: string;
+    instanceId: string;
+    listing?: string;
+    expectedInstances?: number;
+    concurrency?: number;
+    maxPendingBacklog?: number;
+    maxRunningTimeSec?: number;
+    deviceOs?: string;
+    sdkLanguage?: string;
+    sdkVersion?: string;
+    cliVersion?: string;
+    protocolVersions?: string[];
+    preferredProtocolVersion?: string;
+    [key: string]: unknown;
+}
+/**
+ * Full response from the registration endpoint, including agent data and tokens.
+ */
+export interface RegistrationResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    pamToken?: string;
+    [key: string]: unknown;
+}
+/**
+ * Error thrown when the API key is permanently invalid (revoked, expired, etc.).
+ * This is a fatal error — the agent should shut down.
+ */
+export declare class AgentAuthFatalError extends Error {
+    constructor(message: string);
+}
+export declare class AgentAuth {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private accessToken;
+    private refreshTokenValue;
+    private refreshLock;
+    private registrationPayload;
+    constructor(apiKey: string, baseUrl: string);
+    /**
+     * Connect the agent and obtain initial JWT + refresh token.
+     * Connect is the auth entry point for runtime credential issuance.
+     *
+     * Sends POST to /api/v1/auth/agent/connect with the API key in the
+     * Bearer header and the connect payload as JSON body.
+     * Stores the payload for re-connect on refresh token invalidation.
+     */
+    init(registrationPayload: RegistrationPayload): Promise<RegistrationResult>;
+    /**
+     * Get the current access token (JWT). Returns null if init() has not been called.
+     */
+    getAccessToken(): string | null;
+    /**
+     * Get the API key.
+     */
+    getApiKey(): string;
+    /**
+     * Refresh the JWT. Uses a Promise-based mutex so concurrent callers
+     * share a single refresh request instead of racing.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Perform the actual refresh call. On REFRESH_TOKEN_INVALID, falls back
+     * to full re-init. On API_KEY_INVALID, throws a fatal error.
+     */
+    private _doRefresh;
+    /**
+     * Fetch wrapper that automatically attaches the Bearer token and
+     * retries once on 401 after refreshing the token. Injects the cached
+     * `X-Write-Affinity` header on outgoing requests and captures any new
+     * value from responses, so every call through AgentAuth participates
+     * in read-replica routing automatically — no per-call-site wiring
+     * required.
+     */
+    authenticatedFetch(url: string, init?: RequestInit): Promise<Response>;
+}

package/dist/runtime/agent-auth.js

@@ -0,0 +1 @@
+import{CURRENT_PROTOCOL_VERSION as e,PROTOCOL_VERSION_HEADER as t}from"./protocol-version.js";import{captureAffinity as r,injectAffinity as s}from"./write-affinity.js";export class AgentAuthFatalError extends Error{constructor(e){super(e),this.name="AgentAuthFatalError"}}export class AgentAuth{constructor(e,t){if(this.accessToken=null,this.refreshTokenValue=null,this.refreshLock=null,this.registrationPayload=null,!e)throw new Error("apiKey is required");if(!t)throw new Error("baseUrl is required");this.apiKey=e,this.baseUrl=t.replace(/\/+$/,"")}async init(a){const o=`${this.baseUrl}/api/v1/auth/agent/connect`;this.registrationPayload=a;const i={Authorization:`Bearer ${this.apiKey}`,"Content-Type":"application/json",[t]:e};s(i);const n=await fetch(o,{method:"POST",headers:i,body:JSON.stringify(a)});if(r(n.headers),!n.ok){const e=await n.json().catch(()=>({}));throw new AgentAuthFatalError(`Agent registration failed: ${e.error??`HTTP ${n.status}`}`)}const h=await n.json();return this.accessToken=h.accessToken,this.refreshTokenValue=h.refreshToken,h}getAccessToken(){return this.accessToken}getApiKey(){return this.apiKey}async refresh(){if(this.refreshLock)await this.refreshLock;else{this.refreshLock=this._doRefresh();try{await this.refreshLock}finally{this.refreshLock=null}}}async _doRefresh(){const e=`${this.baseUrl}/api/v1/auth/agent/refresh`,t={Authorization:`Bearer ${this.apiKey}`,"Content-Type":"application/json"};s(t);const a=await fetch(e,{method:"POST",headers:t,body:JSON.stringify({refreshToken:this.refreshTokenValue})});if(r(a.headers),a.ok){const e=await a.json();return this.accessToken=e.accessToken,void(this.refreshTokenValue=e.refreshToken)}const o=await a.json().catch(()=>({}));if("REFRESH_TOKEN_INVALID"!==o.code){if("API_KEY_INVALID"===o.code)throw new AgentAuthFatalError(`API key invalid or revoked: ${o.error??"API_KEY_INVALID"}`);throw new Error(`Token refresh failed: ${o.error??`HTTP ${a.status}`}`)}if(!this.registrationPayload)throw new Error("Cannot re-register: no registration payload stored. Call init() with a payload first.");await this.init(this.registrationPayload)}async authenticatedFetch(a,o){const i=async i=>{const n=new Headers(o?.headers);n.set("Authorization",`Bearer ${i}`),n.has(t)||n.set(t,e);const h={};s(h);for(const[e,t]of Object.entries(h))n.set(e,t);const c=await fetch(a,{...o,headers:n});return r(c.headers),c},n=this.accessToken;if(!n)throw new Error("AgentAuth not initialized — call init() first");const h=await i(n);if(401!==h.status)return h;await this.refresh();const c=this.accessToken;if(!c)throw new Error("Failed to obtain access token after refresh");return i(c)}}

package/dist/runtime/agent-instance.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Agent Instance Runtime - Phase 3 Three-Tier Connection Model
+ *
+ * Implements the three-tier connection architecture:
+ * - controlClient: long-lived, subscribes to control channel
+ * - taskClient: per-task, holds T2, destroyed after handler exit
+ * - streamClient: per-stream, holds T7a, managed by StreamClient from Stream SDK
+ *
+ * Key features:
+ * - Unified createStream() with direction, onActivate, metadata, external, format
+ * - Shared stream registry with ref-counting
+ * - Task credential cache for post-handler operations
+ * - Instance-level publishTerminal() and failStream()
+ * - onActivate processing model
+ * - Consumer session API (TaskSession)
+ */
+import PubNub from 'pubnub';
+import { type ArtifactRef } from './artifacts.js';
+import { type JsonValue } from './pubnub-types.js';
+import { type AgentCard } from './agent-registry.js';
+import { type StreamObject, type OnActivateCallback } from './stream-context.js';
+import { TaskClient } from './task-client.js';
+import { type CdmConfig } from './cdm-config.js';
+/**
+ * A single artifact entry within HandlerResult.artifacts.
+ */
+export type ArtifactEntry = {
+    data: Buffer | string;
+    mimeType: string;
+    fileName?: string;
+    /** Declared output ID from the card's io.outputs[].id. Included in artifact events. */
+    outputId?: string;
+};
+/**
+ * Return type for agent task handlers.
+ */
+export type HandlerResult = {
+    /** Zero or more output artifacts. Published in array order before the terminal event. */
+    artifacts?: ArtifactEntry[];
+};
+/**
+ * Handler function signature for processing agent tasks.
+ */
+export type HandlerFn = (task: StartTaskMessage, ctx?: TaskContext) => Promise<HandlerResult>;
+/**
+ * Presence state for agent instances, used for load tracking.
+ */
+export interface AgentInstancePresenceState {
+    instanceId: string;
+    activeTasks: number;
+    activeStreams: number;
+    concurrency: number;
+    startedAt: number;
+    preferredProtocolVersion: string;
+    protocolVersions: string[];
+}
+export interface AgentInstanceOptions {
+    pubnub?: PubNub;
+    token?: string;
+    userId?: string;
+    agentName: string;
+    description?: string;
+    onStartTask?: (task: StartTaskMessage, pubnub: PubNub) => Promise<void>;
+    onCancelTask?: (taskId: string, pubnub: PubNub) => Promise<void>;
+    artifactBasePath?: string;
+    handler?: HandlerFn;
+    onError?: (taskId: string, error: Error) => Promise<void>;
+    logChannel?: string;
+    /** @internal Used by tests only — not a public API. Always auto-generated at runtime. */
+    instanceId?: string;
+    concurrency?: number;
+    expectedInstances?: number;
+    maxPendingBacklog?: number;
+    maxRunningTimeSec?: number;
+    card: AgentCard;
+    cardRef?: string;
+    cardSummary?: string;
+    listing?: 'playground' | 'private' | 'public';
+    baseUrl?: string;
+    cdmUrl?: string;
+}
+/**
+ * Request part item within a StartTask message.
+ * Each part may include a `partId` referencing a declared input in io.inputs[].id.
+ * Explicit optional fields match the Python SDK's RequestPart for cross-SDK parity.
+ * The index signature allows forward-compatible wire evolution.
+ */
+export interface RequestPart {
+    partId?: string;
+    text?: string;
+    contentType?: string;
+    /** Artifact reference attached by the backend (for uploaded files) or
+     *  the consumer SDK (for inline files). Use ctx.downloadInputArtifact(part)
+     *  to get the raw bytes. */
+    artifactRef?: ArtifactRef;
+    [key: string]: JsonValue | ArtifactRef | undefined;
+}
+export interface StartTaskMessage {
+    type: 'StartTask';
+    taskId: string;
+    agentName?: string;
+    ownerId: string;
+    orgId?: string;
+    taskKind?: string;
+    duration?: number;
+    durationExpiresAtMs?: number;
+    requestParts?: RequestPart[];
+    callerClaims?: Record<string, JsonValue>;
+    requestSummary?: Record<string, JsonValue>;
+    hasStream?: boolean;
+    writeToken?: string;
+    controlToken?: string;
+    /** Consumer's public key for E2E encryption (passed through from SendMessage). */
+    consumerPublicKey?: string;
+    /** Protocol version pinned at task creation. */
+    protocolVersion?: string;
+}
+export interface CreateStreamOptions {
+    direction?: 'outbound' | 'inbound' | 'bidirectional';
+    onActivate?: OnActivateCallback;
+    metadata?: Record<string, unknown>;
+    external?: boolean;
+    format?: 'bytes' | 'events';
+    bundleSizeBytes?: number;
+    maxLatencyMs?: number;
+    /** Key from the card's streams block. Defaults to "_default". */
+    declaredStream?: string;
+    /**
+     * Grace period in ms to wait after stream_started is published before
+     * returning the StreamClient for outbound/bidirectional streams. Gives
+     * the consumer time to subscribe. Defaults to 1000ms. Set to 0 to skip.
+     */
+    subscribeGraceMs?: number;
+}
+/**
+ * Context object passed to handlers for reporting status during execution.
+ */
+export interface TaskContext {
+    reportStatus: (message: string) => void;
+    taskId: string;
+    /** Typed request parts from the StartTask message (empty array when none provided). */
+    readonly requestParts: RequestPart[];
+    createStream: (options?: CreateStreamOptions) => Promise<StreamObject>;
+    taskClient: TaskClient;
+    cancelSignal: AbortSignal;
+    readonly isCancelled: boolean;
+    readonly isExpired: boolean;
+    readonly hasStream: boolean;
+    /** Consumer's public key for E2E encryption, if provided in the task submission. */
+    readonly consumerPublicKey: string | undefined;
+    /** Download the file/data from a request part's artifactRef.
+     *  For inline: decodes base64 data. For file: uses pubnub.downloadFile(). */
+    downloadInputArtifact: (part: RequestPart) => Promise<Buffer>;
+    /** Publish an artifact mid-execution. Small data is inlined; large data
+     *  uses the pre-signed URL upload flow (backend publishes the event). */
+    publishArtifact: (data: Buffer | string, options?: {
+        mimeType?: string;
+        fileName?: string;
+        outputId?: string;
+    }) => Promise<void>;
+}
+export interface CancelTaskMessage {
+    type: 'CancelTask';
+    taskId: string;
+    reason?: string;
+    caller?: string;
+    protocolVersion?: string;
+}
+export interface ExpireTaskMessage {
+    type: 'ExpireTask';
+    taskId: string;
+    agentName?: string;
+    reason?: string;
+    protocolVersion?: string;
+}
+export interface SwitchEnvironmentMessage {
+    type: 'SwitchEnvironment';
+    environment: string;
+    pamToken?: string;
+    protocolVersion?: string;
+}
+export interface ControlMessage {
+    type: 'PauseTask' | 'ResumeTask' | 'RetryTask' | 'TerminateTask';
+    taskId: string;
+    caller?: string;
+    protocolVersion?: string;
+}
+/** Numeric precedence for LOG_LEVEL threshold filtering. */
+export declare const _LOG_LEVEL_ORDER: Record<string, number>;
+/** Resolve the effective LOG_LEVEL from env (default: "info"). */
+export declare function _resolveLogLevel(): number;
+/**
+ * Resolve the effective `maxRunningTimeSec` for an agent instance from its
+ * two possible sources: the constructor option (`opts.maxRunningTimeSec`)
+ * and the agent card's declared value (`card.runtime.maxRunningTimeSec`).
+ *
+ * Precedence is opts-first, card-fallback. When both are set and disagree,
+ * opts wins (it's an explicit programmatic override) and the SDK emits a
+ * one-time info-level log so the divergence is visible rather than silent.
+ *
+ * Exported for unit testing; callers inside this module should use the
+ * resolved `effectiveMaxRunningTimeSec` constant rather than reading either
+ * source directly.
+ */
+export declare function resolveMaxRunningTimeSec(optsValue: number | undefined, cardValue: number | undefined): number | undefined;
+/**
+ * Compute the `durationMinutes` the SDK passes to the `streamSetup` Function
+ * for a given task. Pure helper with no side effects — exported for testing.
+ *
+ * Rules:
+ * - If the StartTask message carries an explicit `duration`, it wins.
+ * - Pipe tasks with no `task.duration` fall back to 60 minutes.
+ * - Request tasks with no `task.duration` derive from
+ *   `effectiveMaxRunningTimeSec` via `Math.ceil(... / 60)`; when that value
+ *   is absent the final fallback is 60 minutes (3600 seconds).
+ */
+export declare function computeStreamDurationMinutes(taskDuration: number | undefined, isPipeTask: boolean, effectiveMaxRunningTimeSec: number | undefined): number;
+export interface AgentInstanceHandle {
+    stop: () => void;
+    agentName: string;
+    instanceId: string;
+    pubnub: PubNub;
+    subscribeKey: string;
+    taskClient: TaskClient;
+    publishTerminal: (taskId: string, event: Record<string, JsonValue>) => Promise<void>;
+    failStream: (streamId: string, reason: string) => Promise<void>;
+    cdmConfig: CdmConfig | null;
+}
+export declare const startAgentInstance: (opts: AgentInstanceOptions) => Promise<AgentInstanceHandle>;
+export declare const artifactUtils: {
+    buildArtifactRef: (input: import("./artifacts.js").BuildArtifactInput) => ArtifactRef;
+    shouldInlineArtifact: (sizeBytes: number, inlineLimit?: number) => boolean;
+};

package/dist/runtime/agent-instance.js

@@ -0,0 +1 @@
+import{StreamClient as e}from"../stream/index.js";import{buildArtifactRef as t,shouldInlineArtifact as a,decodeInlineArtifact as r}from"./artifacts.js";import{createPubNubClient as s}from"./pubnub-client.js";import{createChannelManager as n}from"./channel-manager.js";import{toPayload as o}from"./pubnub-types.js";import{connectAgent as i,getAgent as d}from"./agent-registry.js";import{parseStreamSetupResponse as c,parseStreamSetupError as l}from"./stream-setup-helper.js";import{DEFAULTS as u}from"../defaults.js";import{getEnv as m}from"../env.js";import{uploadFile as f}from"./file-upload.js";import{StaticAuthProvider as p}from"./auth-provider.js";import{StreamRegistry as k}from"./stream-registry.js";import{CredentialCache as I}from"./credential-cache.js";import{createStreamObject as h,createExternalStreamObject as y,runOnActivate as g}from"./stream-context.js";import{TaskClient as w}from"./task-client.js";import{fetchCdmConfig as b}from"./cdm-config.js";import{AgentAuth as v,AgentAuthFatalError as T}from"./agent-auth.js";import{CURRENT_PROTOCOL_VERSION as S,SUPPORTED_PROTOCOL_VERSIONS as $,isProtocolVersionSupported as E}from"./protocol-version.js";const K=async(e,t,a,r,s,i=S)=>{const d=n(r);try{await e.publish({channel:d.taskChannel(t,a),message:o({...s,protocolVersion:i}),storeInHistory:!0,sendByPost:!0,meta:o({agentName:r,taskId:t,protocolVersion:i})})}catch{}};export const _LOG_LEVEL_ORDER={error:0,warn:1,info:2,debug:3};export function _resolveLogLevel(){const e=(m("LOG_LEVEL")??"info").toLowerCase();return _LOG_LEVEL_ORDER[e]??_LOG_LEVEL_ORDER.info}const x=(e,t,a)=>{const r=_resolveLogLevel();if((_LOG_LEVEL_ORDER[e]??_LOG_LEVEL_ORDER.info)>r)return;const s={level:e,message:t,ts:Date.now(),...a};"error"===e?console.error("[AgentInstance]",s):"warn"===e?console.warn("[AgentInstance]",s):console.log("[AgentInstance]",s)};export function resolveMaxRunningTimeSec(e,t){return void 0!==e&&void 0!==t&&e!==t&&console.info(`[AgentInstance] opts.maxRunningTimeSec (${e}) overrides card.runtime.maxRunningTimeSec (${t}).`),e??t}export function computeStreamDurationMinutes(e,t,a){return"number"==typeof e?e:t?60:Math.ceil((a??3600)/60)}const A=async(e,r,s,n,o,i,d,c,l)=>{const u={type:"artifact",taskId:r};if(c&&(u.outputId=c),a(o.length))await K(e,r,s,n,{...u,artifactRef:t({data:o,mimeType:i,fileName:d})});else{if(!l)throw new Error("Artifact size exceeds the inline threshold but no baseUrl is configured. Set baseUrl in AgentInstanceOptions to enable the pre-signed URL upload flow.");await f(l,{role:"provider-output",taskId:r,fileName:d??`${r}-artifact`,fileSize:o.length,mimeType:i,outputId:c},o)}};async function _(e,t){const a=`setup.${t.orgId}.${t.taskId}`,r={type:"stream_setup",taskId:t.taskId,orgId:t.orgId,agentName:t.agentName,streamId:t.streamId,channel:t.channel,direction:t.direction,format:t.format,taskKind:t.taskKind,durationMinutes:t.durationMinutes,affinity:t.affinity,declaredStream:t.declaredStream??"_default",protocolVersion:S};t.phase&&(r.phase=t.phase),t.metadata&&(r.metadata=t.metadata);try{throw await e.publish({channel:a,message:o(r),storeInHistory:!1,sendByPost:!0}),new Error("stream_setup publish should have been aborted by Function")}catch(e){const t=l(e);if(t)throw new Error(`Stream setup failed: [${t.code}] ${t.message}`);const a=c(e);if(a)return{token:a.token,tokenTtlMinutes:a.tokenTtlMinutes};throw e}}export const startAgentInstance=async t=>{const a=t.agentName;if(!a)throw new Error("agentName is required: provide opts.agentName");if(!/^[a-zA-Z0-9_]+$/.test(a))throw new Error("agentName must contain only alphanumeric characters and underscores (no hyphens)");const o=n(a),c=t.instanceId??`AG-${a}-${crypto.randomUUID()}`,l=t.token;let f,N=null,R="playground",C=R;if(t.pubnub){const e=t.pubnub._configuration?.keySet,a={publishKey:e?.publishKey??"",subscribeKey:e?.subscribeKey??""};f={playground:a,network:a}}else N=await b(t.cdmUrl),f={playground:N.playground,network:N.network},console.log("[AgentInstance] CDM config loaded — environment switching enabled (playground + network)");const P=m("BLOCKS_API_KEY");if(!P)throw new Error("BLOCKS_API_KEY is required. Run 'blocks publish' to set up credentials.");let M;const L=t.baseUrl??N?.api.baseUrl;let j,U;if(P&&L&&(M=new v(P,L),console.log("[AgentInstance] AgentAuth created — will authenticate via connect")),N){const e=t.baseUrl??N.api.baseUrl,r=await d(a,{baseUrl:e});r?(j=r.listing,R="playground"===j?"playground":"network",console.log(`[AgentInstance] Registry listing: ${j} — using ${R} environment`)):console.warn(`[AgentInstance] Agent "${a}" not found in registry — defaulting to playground environment`),C=R}let q=!1;if(t.pubnub)U=t.pubnub,q=!1,l&&U.setToken(l);else{const e=f[C];U=s({publishKey:e.publishKey,subscribeKey:e.subscribeKey,userId:c,presenceTimeout:20}),q=!0,l&&U.setToken(l)}let D=f[C].subscribeKey,O=f[C].publishKey;const V=new w({subscribeKey:D,authProvider:l?new p(l):void 0,baseUrl:t.baseUrl??N?.api.baseUrl,agentAuth:M,createPubNub:()=>{const e=s({publishKey:O,subscribeKey:D,userId:`${c}-taskclient`});return l&&e.setToken(l),e}}),B=t.concurrency??u.concurrency,F=t.expectedInstances??u.expectedInstances,G=t.maxPendingBacklog,z=resolveMaxRunningTimeSec(t.maxRunningTimeSec,t.card?.runtime?.maxRunningTimeSec),H=Date.now();let Y=0;const W=new k,Z=new I,J=new Map,Q=new Map,X=new Map,ee=new Map,te=new Map,ae=new Set,re=new Set,se=new Map,ne=new Set,oe=new Map;let ie;t.logChannel;const de=o.controlChannel(),ce=async()=>{if("function"==typeof U.setState)try{await U.setState({channels:[de],state:{instanceId:c,activeTasks:Y,activeStreams:W.activeStreamCount,concurrency:B,startedAt:H,preferredProtocolVersion:S,protocolVersions:[...$]}})}catch{}},le=(e,t)=>{const a=J.get(e);a&&(a.delete(t),0===a.size&&J.delete(e))},ue=async e=>{(e=>{for(const[t,a]of J)a.has(e)&&(a.delete(e),0===a.size&&J.delete(t))})(e);const t=W.releaseAllForTask(e);for(const e of t)if(e.streamClient)try{await e.streamClient.end()}catch{}},me=async(e,t)=>{le(e,t);const a=W.get(e);if(0===W.release(e,t)&&a?.streamClient){console.log("[AgentInstance]",{level:"info",message:"last-ref teardown",event:"stream_registry_last_ref_teardown",streamId:e,affinity:a.affinity,releasingTaskId:t,ts:Date.now()});try{await a.streamClient.end()}catch{}}ce().catch(()=>{})},fe=async(e,t)=>{const a=W.forceRemove(e);if((e=>{J.delete(e)})(e),a){if(a.streamClient)try{await a.streamClient.end()}catch{}for(const e of a.taskIds){const a=Z.get(e);if(a){try{const r=f[a.environment??R]??f[R],n=s({publishKey:r.publishKey,subscribeKey:r.subscribeKey,userId:c});n.setToken(a.writeToken),await K(n,e,a.orgId,a.agentName,{type:"terminal",taskId:e,state:"failed",error:t}),n.destroy()}catch{}Z.remove(e)}}await ce()}},pe=async(e,t)=>{const a=Z.get(e);if(!a)throw new Error(`No cached credentials for task ${e}`);const r=f[a.environment??R]??f[R],n=s({publishKey:r.publishKey,subscribeKey:r.subscribeKey,userId:c});n.setToken(a.writeToken);try{await K(n,e,a.orgId,a.agentName,{...t,type:"terminal",taskId:e})}finally{n.destroy()}await ue(e),Z.remove(e),await ce()},ke=async(s,n,i,d,c)=>{const u=a,m="pipe"===s.taskKind,f=m?"pipe":"request",k=computeStreamDurationMinutes(s.duration,m,z);if(m&&"number"==typeof s.durationExpiresAtMs){const e=Math.max(0,s.durationExpiresAtMs-Date.now());if(e>0){const t=setTimeout(()=>{ae.add(s.taskId),c.abort()},e);se.set(s.taskId,t)}}await K(n,s.taskId,d,u,{type:"progress",taskId:s.taskId,progress:0,state:"running"}),oe.set(s.taskId,0);let I=0,w=null,b=null;const v=()=>{if(null===w)return;const e=w;w=null,I=Date.now(),K(n,s.taskId,d,u,{type:"progress",taskId:s.taskId,message:e}).catch(()=>{})},T={taskId:s.taskId,requestParts:s.requestParts??[],reportStatus:e=>{ee.set(s.taskId,e);const t=Date.now();if(t-I>=1e3)w=null,I=t,K(n,s.taskId,d,u,{type:"progress",taskId:s.taskId,message:e}).catch(()=>{});else if(w=e,!b){b=setTimeout(()=>{b=null,v()},1e3-(t-I))}},get isCancelled(){return c.signal.aborted},get isExpired(){return ae.has(s.taskId)},hasStream:!!s.hasStream,cancelSignal:c.signal,taskClient:V,consumerPublicKey:s.consumerPublicKey,downloadInputArtifact:async e=>{const t=e.artifactRef;if(!t)throw new Error(`Request part has no artifactRef (partId: ${e.partId??"none"})`);if("inline"===t.kind)return Buffer.from(r(t));if(!t.channel||!t.fileId||!t.fileName)throw new Error("File artifactRef missing channel, fileId, or fileName");if(!n.downloadFile)throw new Error("PubNub client does not support downloadFile");const a=await n.downloadFile({channel:t.channel,id:t.fileId,name:t.fileName}),s=a?.data;if(Buffer.isBuffer(s))return s;if(s instanceof Uint8Array)return Buffer.from(s);if(s&&"function"==typeof s.arrayBuffer){const e=await s.arrayBuffer();return Buffer.from(e)}throw new Error("Unexpected downloadFile response format")},publishArtifact:async(e,t)=>{const a="string"==typeof e?Buffer.from(e,"utf-8"):e,r=t?.mimeType??"application/octet-stream",o=L?{baseUrl:L,authProvider:l?new p(l):void 0,agentAuth:M}:void 0;await A(n,s.taskId,d,u,a,r,t?.fileName,t?.outputId,o)},createStream:async a=>{if(void 0!==a&&("object"!=typeof a||null===a||Array.isArray(a)))throw new TypeError("createStream expects an options object. The positional streamId argument was removed; move any declared-stream key into CreateStreamOptions.declaredStream. See SDK_CONTRACT §8.2.1.");if(!s.hasStream)throw new Error("Streaming was not negotiated for this task. Ensure the agent card is registered with streaming capability.");const r=t.card.streams;if(!r||0===Object.keys(r).length)throw new Error("Agent card has no streams block. Streaming requires declared streams in the card.");const i=Object.keys(r);let c;if(a?.declaredStream)c=a.declaredStream;else{if(1!==i.length)throw new Error(`Card declares multiple streams (${i.join(", ")}). Specify declaredStream in CreateStreamOptions.`);c=i[0]}const l=r[c];if(!l)throw new Error(`Stream "${c}" is not declared in the agent card. Available streams: ${i.join(", ")}`);const p=a?.direction??l.direction,I=a?.format??l.format;if(a?.direction&&a.direction!==l.direction)throw new Error(`Direction "${a.direction}" conflicts with card declaration "${l.direction}" for stream "${c}".`);if(a?.format&&a.format!==l.format)throw new Error(`Format "${a.format}" conflicts with card declaration "${l.format}" for stream "${c}".`);const w=a?.external??!1,b=a?.metadata,v=a?.onActivate,T=l.affinity??"dedicated";if("shared"===T&&w)throw new Error(`Shared-affinity external streams are not supported. Declared stream '${c}' has affinity: 'shared' and createStream was called with external: true. Shared affinity requires a single SDK-managed writer with per-task ref-counting; external streams delegate the writer entirely. Use affinity: 'dedicated' with external: true, or affinity: 'shared' without external.`);if(!m){if("shared"===T)throw new Error(`Shared-affinity streams are not supported on request tasks. Declared stream '${c}' has affinity: 'shared'. Request tasks are single-shot; cross-task broadcast is inherently a pipe-task concept. Use affinity: 'dedicated' or remove 'request' from the agent card's taskKinds.`);if("outbound"!==p)throw new Error("Request tasks only support outbound streams");if(w)throw new Error("Request tasks cannot use external streams")}let S;if("shared"===T)S=c;else{const e=(oe.get(s.taskId)??0)+1;oe.set(s.taskId,e),S=`${s.taskId}-${e}`}const $=o.streamChannel(S);if("shared"===T){const e=J.get(S)?.get(s.taskId);if(e)return e}const{entry:E,isNew:K,isNewForTask:x}=W.acquire(S,s.taskId,{direction:p,format:I,external:w,affinity:T});Z.addStream(s.taskId,S);const A=e=>{if("shared"!==T)return;let t=J.get(S);t||(t=new Map,J.set(S,t)),t.set(s.taskId,e)};if(!x){E.setupPromise&&await E.setupPromise;const e=J.get(S)?.get(s.taskId);if(e)return e;if(E.streamClient){const e=h(S,E.streamClient,s.taskId,{releaseStream:me});return A(e),e}throw new Error(`Stream "${S}" same-task reacquire reached an impossible state: setup completed but no client installed. This indicates a logic error in the shared-stream handle cache.`)}if(!K)try{if(E.setupPromise&&await E.setupPromise,"shared"===T&&await(async()=>{await _(n,{taskId:s.taskId,orgId:d,agentName:u,streamId:S,channel:$,direction:p,format:I,taskKind:f,durationMinutes:k,affinity:T,phase:"activate",metadata:b,declaredStream:c})})(),E.streamClient){const e=h(S,E.streamClient,s.taskId,{releaseStream:me});return A(e),e}if(w)return y(S,$,"",async()=>{throw new Error("External stream already activated")});throw new Error(`Stream "${S}" exists but has no client`)}catch(e){le(S,s.taskId);try{await W.release(S,s.taskId)}catch{}throw e}let N,R;E.setupPromise=new Promise((e,t)=>{N=e,R=t}),E.setupPromise.catch(()=>{});const C=w?"token_request":"embedded";let P;try{P=await _(n,{taskId:s.taskId,orgId:d,agentName:u,streamId:S,channel:$,direction:p,format:I,taskKind:f,durationMinutes:k,affinity:T,phase:C,metadata:b,declaredStream:c})}catch(e){R(e),le(S,s.taskId);try{await W.release(S,s.taskId)}catch{}throw e}if(w){N(),E.setupPromise=null;const e=P.token??"";return y(S,$,e,async e=>{await _(n,{taskId:s.taskId,orgId:d,agentName:u,streamId:S,channel:$,direction:p,format:I,taskKind:f,durationMinutes:k,affinity:T,phase:"activate",metadata:e?.metadata??b,declaredStream:c})})}const M=P.token;if(!M){const e=new Error("No T7a token received from stream setup handshake");R(e),le(S,s.taskId);try{await W.release(S,s.taskId)}catch{}throw e}const L=new e({subscribeKey:D,publishKey:O,token:M,agentName:u,streamId:S,channel:$,format:I,direction:p,affinity:T,gating:m,bundleSizeBytes:a?.bundleSizeBytes,maxLatencyMs:a?.maxLatencyMs});E.streamClient=L;const j=h(S,L,s.taskId,{releaseStream:me});if(A(j),N(),E.setupPromise=null,"outbound"===p||"bidirectional"===p){const e=a?.subscribeGraceMs??1e3;e>0&&await new Promise(t=>setTimeout(t,e))}return v&&(E.activated=!0,E.activatePromise=g(S,j,v,fe)),j}};let S;try{S=t.handler?await t.handler(s,T):void 0}finally{oe.delete(s.taskId),b&&(clearTimeout(b),b=null),v()}const $=L?{baseUrl:L,authProvider:l?new p(l):void 0,agentAuth:M}:void 0;if(S?.artifacts&&S.artifacts.length>0)for(const e of S.artifacts){const t="string"==typeof e.data?Buffer.from(e.data,"utf-8"):e.data;await A(n,s.taskId,d,u,t,e.mimeType,e.fileName,e.outputId,$)}const E=c.signal.aborted;if(m){const e=ae.has(s.taskId),t=re.has(s.taskId);if(E||e||t){await ue(s.taskId);const a=E&&!e?"canceled":"completed";await K(n,s.taskId,d,u,{type:"terminal",taskId:s.taskId,state:a,...e?{completionReason:"duration_expired"}:{},...t?{reason:"terminated"}:{}}),Z.remove(s.taskId),x("info",`Task ${s.taskId} ${a}`,{taskId:s.taskId,agentName:u,owner:i})}else x("info",`Task ${s.taskId} handler returned (pipe, no auto-terminal)`,{taskId:s.taskId,agentName:u,owner:i})}else{const e=re.has(s.taskId);await ue(s.taskId);const t=E?"canceled":"completed";await K(n,s.taskId,d,u,{type:"terminal",taskId:s.taskId,state:t,...e?{reason:"terminated"}:{}}),Z.remove(s.taskId),x("info",`Task ${s.taskId} ${t}`,{taskId:s.taskId,agentName:u,owner:i})}},Ie=(e,t)=>{if(x("info",`SwitchEnvironment requested: ${C} -> ${e}`,{pamToken:t?"present":"absent"}),"playground"===e&&"network"===C)return void x("error",`SwitchEnvironment rejected: cannot demote from ${C} to ${e}. Forbidden listing transition.`);if(!t)return void x("error","SwitchEnvironment rejected: pamToken is required but was absent. The backend must include a pamToken in SwitchEnvironment messages.");const a=U,r=q;try{a.removeListener(ye),a.unsubscribe({channels:[de]})}catch{}const n=f[e];if(U=s({publishKey:n.publishKey,subscribeKey:n.subscribeKey,userId:c,presenceTimeout:20}),q=!0,ie=void 0,U.setToken(t),0!==F&&"function"==typeof U.setFilterExpression&&U.setFilterExpression(`meta.instance == '${c}' || meta.broadcast == "true"`),U.addListener(ye),U.subscribe({channels:[de]}),r)try{a.destroy()}catch{}C=e,D=n.subscribeKey,O=n.publishKey,V.updateKeys(n.subscribeKey,n.publishKey),x("info",`Switched to ${e} environment`),ce().catch(()=>{})},he=(()=>{let e=!1;return t=>{if("PNAccessDeniedCategory"===t&&!e){e=!0,console.error(`[AgentInstance] PAM token expired or revoked — agent ${c} is no longer receiving tasks. Re-register the agent to resume.`);try{U.destroy()}catch{}}}})(),ye={status:e=>{const t=e,a=String(t.category??""),r=String(t.operation??"");"PNConnectedCategory"===a?console.log(`[AgentInstance] PubNub connected to ${de}`):t.error&&console.error(`[AgentInstance] PubNub status: ${a} (op=${r}, code=${t.statusCode})`),he(a)},message:e=>{const r=e.message;if(!r)return;if("SwitchEnvironment"===r.type){const e=r,t=e.environment;return void(t&&t!==C&&t in f&&Ie(t,e.pamToken))}(async(e,r)=>{if("StartTask"===e.type){const n=C,o=((e,t)=>{if("string"==typeof e&&e.length>0)return e;const a=t?.sub;return"string"==typeof a&&a.length>0?a:"anonymous"})(e.ownerId,e.callerClaims),i=e.orgId??o;if(ne.has(e.taskId))return void x("warn",`Ignoring duplicate StartTask for in-flight task ${e.taskId}`,{taskId:e.taskId});const d=Boolean(r?.broadcast);if(e.protocolVersion&&!E(e.protocolVersion))return d?void x("debug",`Ignoring broadcast StartTask ${e.taskId} with unsupported protocolVersion ${e.protocolVersion}`,{taskId:e.taskId}):(await K(U,e.taskId,i,a,{type:"terminal",taskId:e.taskId,state:"failed",error:"unsupported_protocol_version"},e.protocolVersion),void x("warn",`Task ${e.taskId} rejected: unsupported protocolVersion ${e.protocolVersion}`,{taskId:e.taskId,instanceId:c}));if("pipe"===(e.taskKind||"request")){const t=e.duration,r=e.durationExpiresAtMs;if(null==t||!Number.isInteger(t)||t<1||t>43200||"number"!=typeof r||r<=0)return x("error",`Task ${e.taskId} rejected: pipe StartTask with invalid duration (duration=${t}, durationExpiresAtMs=${r})`,{taskId:e.taskId,instanceId:c}),void await K(U,e.taskId,i,a,{type:"terminal",taskId:e.taskId,state:"failed",error:"invalid_start_task"},e.protocolVersion)}const l=Y+W.activeStreamCount;if(B>0&&l>=B)return d?void x("debug",`Task ${e.taskId} skipped (broadcast, at capacity ${l}/${B})`,{taskId:e.taskId,instanceId:c}):(await K(U,e.taskId,i,a,{type:"terminal",taskId:e.taskId,state:"failed",error:"agent_at_capacity"}),void x("warn",`Task ${e.taskId} rejected: agent at capacity`,{taskId:e.taskId,instanceId:c,activeTasks:Y}));Q.set(e.taskId,o),X.set(e.taskId,i),ne.add(e.taskId),Y++,e.controlToken&&(ie=e.controlToken);const u=new AbortController;te.set(e.taskId,u);let m=null;try{const r=f[n];if(!r.publishKey||!r.subscribeKey)throw new Error("Per-task PubNub client requires valid pub/sub keys. When using an injected PubNub client, ensure it was created with publishKey and subscribeKey.");m=s({publishKey:r.publishKey,subscribeKey:r.subscribeKey,userId:c}),e.writeToken&&m.setToken(e.writeToken),Z.set(e.taskId,{ownerId:o,orgId:i,writeToken:e.writeToken??"",agentName:a,environment:n}),await ce(),t.onStartTask?await t.onStartTask(e,m):await ke(e,m,o,i,u)}catch(r){const s=r?.message??"Agent instance error",n=m??U;try{await ue(e.taskId)}catch{}await K(n,e.taskId,i,a,{type:"terminal",taskId:e.taskId,state:"failed",error:s}),t.onError&&await t.onError(e.taskId,r),x("error",s,{taskId:e.taskId}),Z.remove(e.taskId)}finally{const t=se.get(e.taskId);if(t&&(clearTimeout(t),se.delete(e.taskId)),ne.delete(e.taskId),Q.delete(e.taskId),X.delete(e.taskId),ee.delete(e.taskId),te.delete(e.taskId),ae.delete(e.taskId),re.delete(e.taskId),m)try{m.destroy()}catch{}Y--,0===Y&&ie&&U.setToken(ie),await ce()}}else if("CancelTask"===e.type){const t=te.get(e.taskId);t?(t.abort(),x("info",`Task ${e.taskId} cancel requested (cooperative)`,{taskId:e.taskId,instanceId:c})):Z.get(e.taskId)&&await pe(e.taskId,{state:"canceled"})}else if("ExpireTask"===e.type)te.has(e.taskId)?(ae.add(e.taskId),te.get(e.taskId)?.abort(),x("info",`Task ${e.taskId} expired`,{taskId:e.taskId,instanceId:c})):Z.get(e.taskId)&&await pe(e.taskId,{state:"completed",completionReason:"duration_expired"});else if("TerminateTask"===e.type)te.has(e.taskId)?(re.add(e.taskId),te.get(e.taskId)?.abort()):Z.get(e.taskId)&&await pe(e.taskId,{state:"canceled",reason:"terminated"});else if("PauseTask"===e.type){if(ne.has(e.taskId)){const t=X.get(e.taskId)??"anonymous";await K(U,e.taskId,t,a,{type:"system",taskId:e.taskId,status:"paused"})}}else if("ResumeTask"===e.type){if(ne.has(e.taskId)){const t=X.get(e.taskId)??"anonymous";await K(U,e.taskId,t,a,{type:"system",taskId:e.taskId,status:"resumed"})}}else"RetryTask"===e.type&&x("info","RetryTask received (no-op)",{taskId:e.taskId})})(r,e.userMetadata&&"object"==typeof e.userMetadata?e.userMetadata:void 0).catch(e=>{console.error("[AgentInstance] Unhandled error in message handler:",e)})}};U.addListener(ye),i(a,{instanceId:c,description:t.description,scaling:{expectedInstances:F,concurrency:B,maxPendingBacklog:G,maxRunningTimeSec:z},card:t.card,cardRef:t.cardRef,cardSummary:t.cardSummary,listing:j??t.listing,actor:`agent-instance:${c}`,baseUrl:t.baseUrl??N?.api.baseUrl,agentAuth:M}).then(e=>{console.log(`[AgentInstance] Registered agent: ${a} (instance: ${c})`),e.pamToken&&U.setToken(e.pamToken),0!==F&&"function"==typeof U.setFilterExpression&&U.setFilterExpression(`meta.instance == '${c}' || meta.broadcast == "true"`),U.subscribe({channels:[de]}),ce().catch(()=>{})}).catch(e=>{const t=e instanceof Error?e.message:String(e);console.error(`[AgentInstance] Failed to register agent: ${a} — ${t}`),e instanceof T&&process.exit(1)}),x("info",`Agent instance ${c} started (agent name: ${a})`,{agentName:a,event:"agent_instance_started",instanceId:c});return{stop:()=>{try{V.destroy(),U.removeListener(ye),U.unsubscribe({channels:[de]}),q&&U.destroy();for(const e of W.streamIds()){const t=W.get(e);if(t?.streamClient)try{t.streamClient.end()}catch{}}W.clear(),J.clear(),Z.clear()}catch{}},agentName:a,instanceId:c,get pubnub(){return U},get subscribeKey(){return f[C].subscribeKey},taskClient:V,publishTerminal:pe,failStream:fe,cdmConfig:N}};export const artifactUtils={buildArtifactRef:t,shouldInlineArtifact:a};