@blocks-network/sdk 0.1.45

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

@@ -0,0 +1,270 @@
+/**
+ * Agent Registry - REST-based agent card storage and discovery.
+ *
+ * All registry operations (register, fetch, get, remove) use the server-side
+ * REST endpoints at /api/v1/registry/agents which handle App Context operations,
+ * membership indexing, and audit events server-side.
+ */
+import { registryAllChannel, registrySkillChannel, registryVisibilityChannel, registryLogChannel, normalizeSkillSlug } from './channel-manager.js';
+import type { AgentAuth } from './agent-auth.js';
+/**
+ * Scaling configuration for multi-instance support.
+ */
+export interface AgentScaling {
+    expectedInstances: number;
+    concurrency: number;
+    maxPendingBacklog?: number;
+    maxRunningTimeSec?: number;
+}
+/**
+ * Skill object within an AgentCard.
+ */
+export interface AgentSkill {
+    id: string;
+    name: string;
+    description?: string;
+    examples?: string[];
+}
+/**
+ * Agent card payload (input schema) — authored by developers in agent-card.json.
+ *
+ * Uses the 9-section structure: identity, capabilities, io, streams,
+ * security, services, skills, extensions, runtime.
+ */
+export interface AgentCard {
+    identity: {
+        agentName: string;
+        displayName: string;
+        description: string;
+        version: string;
+        provider: {
+            organization: string;
+            url?: string;
+        };
+        documentationUrl?: string;
+        repositoryUrl?: string;
+        iconUrl?: string;
+    };
+    capabilities: {
+        taskKinds: Array<'request' | 'pipe'>;
+    };
+    io?: {
+        inputs?: Array<{
+            id: string;
+            description?: string;
+            contentType: string;
+            required: boolean;
+            example?: unknown;
+            schema?: unknown;
+        }>;
+        outputs?: Array<{
+            id: string;
+            description?: string;
+            contentType: string;
+            guaranteed: boolean;
+            example?: unknown;
+            schema?: unknown;
+        }>;
+    };
+    streams?: Record<string, {
+        direction: string;
+        format: string;
+        description?: string;
+        affinity?: string;
+        schema?: unknown;
+        outboundSchema?: unknown;
+        inboundSchema?: unknown;
+        contentType?: string;
+    }>;
+    security?: {
+        encryption?: {
+            required: boolean;
+            algorithm: string;
+            consumerKeyRequired: boolean;
+            agentPublicKey?: string;
+            agentKeyUrl?: string;
+            documentationUrl?: string;
+        };
+    };
+    services?: {
+        webhooks?: boolean;
+    };
+    skills: AgentSkill[];
+    extensions?: Record<string, unknown>;
+    runtime?: {
+        handler?: string;
+        handlerExport?: string;
+        concurrency?: number;
+        expectedInstances?: number;
+        maxPendingBacklog?: number;
+        maxRunningTimeSec?: number;
+    };
+}
+/**
+ * Agent card payload (output/public schema) — served by the API.
+ * Same as AgentCard minus the `runtime` section.
+ */
+export interface OutputAgentCard {
+    identity: {
+        agentName: string;
+        displayName: string;
+        description: string;
+        version: string;
+        provider: {
+            organization: string;
+            url?: string;
+        };
+        documentationUrl?: string;
+        repositoryUrl?: string;
+        iconUrl?: string;
+    };
+    capabilities: {
+        taskKinds: Array<'request' | 'pipe'>;
+    };
+    io?: AgentCard['io'];
+    streams?: AgentCard['streams'];
+    security?: AgentCard['security'];
+    services?: AgentCard['services'];
+    skills: AgentSkill[];
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Agent entry returned from registry queries.
+ */
+export interface AgentEntry {
+    /** Agent name identifier */
+    agentName: string;
+    /** Display name */
+    displayName: string;
+    /** Human-readable description */
+    description?: string;
+    /** Skill objects from agent card */
+    skills?: AgentSkill[];
+    /** Multi-instance scaling configuration */
+    scaling?: AgentScaling;
+    /** Full agent card payload */
+    card?: AgentCard;
+    /** Optional card reference (PubNub File ID or URL) */
+    cardRef?: string;
+    /** Optional short summary for list views */
+    cardSummary?: string;
+    /** Listing visibility */
+    listing: 'playground' | 'private' | 'public';
+    /** Creation timestamp (ISO string) */
+    createdAt?: string;
+    /** Last update timestamp (ISO string) */
+    updatedAt?: string;
+}
+/**
+ * Options for registering an agent.
+ */
+export interface ConnectAgentOptions {
+    /** @internal Agent instance identifier — auto-generated by startAgentInstance, not caller-supplied. */
+    instanceId: string;
+    /** Human-readable description */
+    description?: string;
+    /** Skill objects advertised by this agent */
+    skills?: AgentSkill[];
+    /** Multi-instance scaling configuration */
+    scaling?: AgentScaling;
+    /** Full agent card payload */
+    card?: AgentCard;
+    /** Optional card reference (PubNub File ID or URL) */
+    cardRef?: string;
+    /** Optional short summary for list views */
+    cardSummary?: string;
+    /** Listing visibility (default: 'playground') */
+    listing?: 'playground' | 'private' | 'public';
+    /** Actor identifier for audit log */
+    actor?: string;
+    /** Request ID for audit log correlation */
+    requestId?: string;
+    baseUrl?: string;
+    /** AgentAuth instance for API key-based authentication */
+    agentAuth?: AgentAuth;
+}
+/**
+ * Result of fetching the agent registry.
+ */
+export interface AgentRegistryResult {
+    agents: AgentEntry[];
+    next?: string;
+    totalCount?: number;
+}
+/**
+ * Audit log event for registry changes.
+ */
+export interface RegistryAuditEvent {
+    event: 'registry.agent.upsert' | 'registry.agent.delete' | 'registry.membership.add' | 'registry.membership.remove' | 'registry.bootstrap' | 'registry.clear';
+    ts: number;
+    source: string;
+    agentName?: string;
+    visibility?: 'public' | 'private';
+    skills?: string[];
+    cardHash?: string;
+    cardRef?: string;
+    summaryHash?: string;
+    channel?: string;
+    action?: string;
+    requestId?: string;
+    actor?: string;
+    etags?: {
+        user?: string;
+        memberships?: string;
+    };
+    note?: string;
+}
+/**
+ * Detect the host operating system via Node.js os.platform().
+ * Returns the raw platform string (e.g. "linux", "darwin", "win32")
+ * or "unknown" if detection fails.
+ */
+declare function detectDeviceOs(): string;
+/**
+ * Register or update an agent in the registry via REST.
+ *
+ * Sends a POST request to the dedicated registry endpoint which handles
+ * all App Context operations (UUID metadata, memberships, audit events)
+ * server-side.
+ */
+export declare function connectAgent(agentName: string, options: ConnectAgentOptions): Promise<{
+    pamToken?: string;
+}>;
+/**
+ * Get a single agent by name.
+ */
+export declare function getAgent(agentName: string, options?: {
+    baseUrl?: string;
+}): Promise<AgentEntry | null>;
+/**
+ * Fetch the agent registry (all agents).
+ */
+export declare function fetchAgentRegistry(options?: {
+    limit?: number;
+    cursor?: string;
+    baseUrl?: string;
+}): Promise<AgentRegistryResult>;
+/**
+ * Fetch agents filtered by skill.
+ */
+export declare function fetchAgentsBySkill(skill: string, options?: {
+    limit?: number;
+    cursor?: string;
+    baseUrl?: string;
+}): Promise<AgentRegistryResult>;
+/**
+ * Fetch agents filtered by listing type.
+ */
+export declare function fetchAgentsByListing(listing: string, options?: {
+    limit?: number;
+    cursor?: string;
+    baseUrl?: string;
+}): Promise<AgentRegistryResult>;
+/**
+ * Remove an agent from the registry.
+ */
+export declare function removeAgent(agentName: string, options?: {
+    baseUrl?: string;
+    agentAuth?: AgentAuth;
+}): Promise<boolean>;
+export { detectDeviceOs, registryAllChannel, registrySkillChannel, registryVisibilityChannel, registryLogChannel, normalizeSkillSlug, };

package/dist/runtime/agent-registry.js

@@ -0,0 +1 @@
+import t from"node:os";import{registryAllChannel as n,registrySkillChannel as e,registryVisibilityChannel as a,registryLogChannel as r,normalizeSkillSlug as s}from"./channel-manager.js";import{getEnv as o}from"../env.js";import{CURRENT_PROTOCOL_VERSION as i,SUPPORTED_PROTOCOL_VERSIONS as c,SDK_VERSION as u,PROTOCOL_VERSION_HEADER as l}from"./protocol-version.js";import{captureAffinity as g,injectAffinity as d}from"./write-affinity.js";function m(){try{return t.platform()}catch{return"unknown"}}async function f(t,n=3,e=500){let a;for(let r=0;r<n;r++)try{return await t()}catch(t){a=t;const s=String(t);if(!(s.includes("ENOTFOUND")||s.includes("ETIMEDOUT")||s.includes("ECONNRESET")||s.includes("NetworkIssues"))||r===n-1)throw t;const o=e*Math.pow(2,r)+100*Math.random();await new Promise(t=>setTimeout(t,o))}throw a}function h(t,n){let e=`${function(t){if(t)return t.replace(/\/+$/,"");throw new Error("[AgentRegistry] baseUrl is required: provide it via options or CDM config")}(n)}/api/v1/registry/agents`;if(t){const n=new URLSearchParams;for(const[e,a]of Object.entries(t))void 0!==a&&""!==a&&n.set(e,a);const a=n.toString();a&&(e+="?"+a)}return e}async function p(t,n){const e=new Headers(n?.headers);e.has(l)||e.set(l,i);const a={};d(a);for(const[t,n]of Object.entries(a))e.set(t,n);const r=await fetch(t,{...n,headers:e});if(g(r.headers),404===r.status)return null;if(!r.ok){const t=(await r.json().catch(()=>({}))).message??`HTTP ${r.status}`;throw new Error(`[AgentRegistry] Request failed: ${t}`)}return{data:await r.json(),status:r.status}}function y(t){return{agentName:t.agentName,displayName:t.name??t.agentName,description:t.description,skills:t.skills,scaling:t.scaling,card:t.card,cardRef:t.cardRef,cardSummary:t.cardSummary,listing:t.listing??"playground",createdAt:t.registeredAt}}export async function connectAgent(t,n){if(!/^[a-zA-Z0-9_]+$/.test(t))throw new Error("agentName must contain only alphanumeric characters and underscores (no hyphens)");h(void 0,n.baseUrl);const e=o("BLOCKS_CLI_VERSION"),a={agentName:t,instanceId:n.instanceId,listing:n.listing,expectedInstances:n.scaling?.expectedInstances,concurrency:n.scaling?.concurrency,maxPendingBacklog:n.scaling?.maxPendingBacklog,maxRunningTimeSec:n.scaling?.maxRunningTimeSec,deviceOs:m(),sdkLanguage:"Node",sdkVersion:u,protocolVersions:[...c],preferredProtocolVersion:i};let r;if(e&&(a.cliVersion=e),!n.agentAuth)throw new Error("[AgentRegistry] agentAuth is required. Set BLOCKS_API_KEY and pass agentAuth to connectAgent.");return r=(await f(async()=>n.agentAuth.init(a))).pamToken??void 0,{pamToken:r}}export async function getAgent(t,n){const e=h({agentName:t},n?.baseUrl),a=await f(async()=>p(e));return a?y(a.data.agent):null}export async function fetchAgentRegistry(t){const n={include:"full"};t?.limit&&(n.limit=String(t.limit)),t?.cursor&&(n.cursor=t.cursor);const e=h(n,t?.baseUrl),a=await f(async()=>p(e));return a?{agents:a.data.agents.map(y),next:a.data.next??void 0,totalCount:a.data.totalCount}:{agents:[],totalCount:0}}export async function fetchAgentsBySkill(t,n){const e={include:"full",skill:t};n?.limit&&(e.limit=String(n.limit)),n?.cursor&&(e.cursor=n.cursor);const a=h(e,n?.baseUrl),r=await f(async()=>p(a));return r?{agents:r.data.agents.map(y),next:r.data.next??void 0,totalCount:r.data.totalCount}:{agents:[],totalCount:0}}export async function fetchAgentsByListing(t,n){const e={include:"full",listing:t};n?.limit&&(e.limit=String(n.limit)),n?.cursor&&(e.cursor=n.cursor);const a=h(e,n?.baseUrl),r=await f(async()=>p(a));return r?{agents:r.data.agents.map(y),next:r.data.next??void 0,totalCount:r.data.totalCount}:{agents:[],totalCount:0}}export async function removeAgent(t,n){const e=h({agentName:t},n?.baseUrl);if(n?.agentAuth){return 404!==(await f(()=>n.agentAuth.authenticatedFetch(e,{method:"DELETE"}))).status}const a=o("BLOCKS_API_KEY");return null!==await f(async()=>p(e,{method:"DELETE",headers:{...a?{Authorization:`Bearer ${a}`}:{}}}))}export{m as detectDeviceOs,n as registryAllChannel,e as registrySkillChannel,a as registryVisibilityChannel,r as registryLogChannel,s as normalizeSkillSlug};

package/dist/runtime/artifacts.d.ts

@@ -0,0 +1,65 @@
+import type PubNub from 'pubnub';
+export interface DownloadedArtifact {
+    data: Uint8Array;
+    mimeType: string;
+    fileName?: string;
+}
+export interface ArtifactRef {
+    kind: 'inline' | 'file';
+    mimeType: string;
+    size: number;
+    hash?: string;
+    /** Base64-encoded data for inline artifacts (kind: 'inline' only) */
+    data?: string;
+    /** PubNub Files identifier (kind: 'file' only) */
+    fileId?: string;
+    /** File name (both variants; required for kind: 'file') */
+    fileName?: string;
+    /** PubNub channel where the file is stored (kind: 'file' only, required).
+     *  Used with fileId and fileName for pubnub.downloadFile() under PAM. */
+    channel?: string;
+    expiresAt?: string;
+}
+export declare const shouldInlineArtifact: (sizeBytes: number, inlineLimit?: number) => boolean;
+export interface BuildArtifactInput {
+    mimeType: string;
+    /** Size in bytes - required if data is not provided */
+    size?: number;
+    hash?: string;
+    /** Raw data for inline artifacts - will be base64 encoded. Accepts
+     *  `Uint8Array` (includes Node `Buffer` at runtime). */
+    data?: Uint8Array;
+    /** File reference for uploaded artifacts. Channel is the PubNub channel
+     *  where the file is stored (required for downloadFile under PAM). */
+    file?: {
+        id: string;
+        name: string;
+        channel: string;
+        expiresAt?: string;
+    };
+    /** Original file name (preserved on inline artifacts too). */
+    fileName?: string;
+    inlineLimit?: number;
+}
+export declare const buildArtifactRef: (input: BuildArtifactInput) => ArtifactRef;
+/**
+ * Decode an inline base64 artifact ref into raw bytes.
+ * Browser-safe: uses atob() + Uint8Array (no Buffer dependency).
+ *
+ * The ArtifactRef shape uses top-level `kind: 'inline'` discriminator
+ * with `data` as a top-level base64 string field (see ArtifactRef
+ * interface and artifact-ref.schema.json).
+ */
+export declare function decodeInlineArtifact(ref: ArtifactRef): Uint8Array;
+/**
+ * Download an artifact from an ArtifactRef.
+ *
+ * - Inline artifacts: decode base64 data directly (no PubNub call).
+ * - File artifacts: call pubnub.downloadFile() using the ref's
+ *   channel, fileId, and fileName.
+ *
+ * Requires a PubNub instance with a valid token granting READ on the
+ * artifact's channel. For TaskSession consumers, the T4 read token
+ * already grants this.
+ */
+export declare function downloadArtifact(ref: ArtifactRef, pubnub: PubNub): Promise<DownloadedArtifact>;

package/dist/runtime/artifacts.js

@@ -0,0 +1 @@
+import{DEFAULTS as e}from"../defaults.js";import{bytesToBase64 as i}from"../stream/bytes.js";export const shouldInlineArtifact=(i,n=e.inlineLimitBytes)=>i<=n;export const buildArtifactRef=n=>{const t=n.inlineLimit??e.inlineLimitBytes,a=n.size??n.data?.length??0;if(shouldInlineArtifact(a,t)||!n.file)return{kind:"inline",mimeType:n.mimeType,size:a,hash:n.hash,data:void 0!==n.data?i(n.data):void 0,fileName:n.fileName};const r=n.file;return{kind:"file",mimeType:n.mimeType,size:a,hash:n.hash,fileId:r.id,fileName:r.name,channel:r.channel,expiresAt:r.expiresAt}};export function decodeInlineArtifact(e){if("inline"!==e.kind||!e.data)throw new Error("ArtifactRef is not an inline artifact or has no data");const i=atob(e.data),n=new Uint8Array(i.length);for(let e=0;e<i.length;e++)n[e]=i.charCodeAt(e);return n}export async function downloadArtifact(e,i){if("inline"===e.kind){if(!e.data)throw new Error("Inline ArtifactRef is missing data");return{data:decodeInlineArtifact(e),mimeType:e.mimeType,fileName:e.fileName}}if("file"===e.kind){if(!e.channel||!e.fileId||!e.fileName)throw new Error("File ArtifactRef is missing required fields: channel, fileId, and fileName are all required");const n=await i.downloadFile({channel:e.channel,id:e.fileId,name:e.fileName}),t=n.data??n;let a;if(t instanceof Uint8Array)a=new Uint8Array(t);else if("undefined"!=typeof Blob&&t instanceof Blob){const e=await t.arrayBuffer();a=new Uint8Array(e)}else if("function"==typeof t?.toArrayBuffer){const e=await t.toArrayBuffer();a=new Uint8Array(e)}else{if("function"!=typeof t?.toBuffer)throw new Error("PubNub downloadFile result has no usable data format");{const e=await t.toBuffer();a=new Uint8Array(e)}}return{data:a,mimeType:e.mimeType,fileName:e.fileName}}throw new Error(`Unknown ArtifactRef kind: ${e.kind}`)}

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

@@ -0,0 +1,39 @@
+/**
+ * AuthProvider interface and StaticAuthProvider implementation.
+ *
+ * All authenticated SDK paths (RPC, file upload, task-read-token) use
+ * AuthProvider to obtain the current Authorization header and to handle
+ * 401 reactive refresh. Static JWT callers use StaticAuthProvider;
+ * ConsumerAuth implements the same interface with proactive + reactive
+ * token refresh.
+ */
+/**
+ * Provides the current Authorization header and handles 401 refresh.
+ *
+ * Implementations:
+ * - StaticAuthProvider: wraps a fixed JWT string, no refresh capability
+ * - ConsumerAuth: manages token acquisition and transparent refresh
+ */
+export interface AuthProvider {
+    /**
+     * Returns the current Authorization header value (e.g. "Bearer <jwt>").
+     * Returns null if no token is available.
+     */
+    getAuthHeader(): string | null;
+    /**
+     * Called by the transport when a request receives a 401 response.
+     * Returns true if a fresh token was acquired and the caller should retry.
+     * Returns false if no refresh is possible and the 401 should propagate.
+     */
+    onAuthFailure(): Promise<boolean>;
+}
+/**
+ * Wraps a static JWT string. No refresh capability -- onAuthFailure()
+ * always returns false.
+ */
+export declare class StaticAuthProvider implements AuthProvider {
+    private readonly token;
+    constructor(token: string);
+    getAuthHeader(): string;
+    onAuthFailure(): Promise<boolean>;
+}

package/dist/runtime/auth-provider.js

@@ -0,0 +1 @@
+export class StaticAuthProvider{constructor(t){this.token=t}getAuthHeader(){return`Bearer ${this.token}`}async onAuthFailure(){return!1}}

package/dist/runtime/cdm-config.d.ts

@@ -0,0 +1,16 @@
+export declare const DEFAULT_CDM_URL = "https://config.blocksnetwork.functions.pdx1.aws.int.ps.pn/config.json";
+export interface CdmKeyset {
+    publishKey: string;
+    subscribeKey: string;
+}
+export interface CdmApiConfig {
+    baseUrl: string;
+    clientId?: string;
+}
+export interface CdmConfig {
+    playground: CdmKeyset;
+    network: CdmKeyset;
+    api: CdmApiConfig;
+}
+export type PnEnvironment = 'playground' | 'network';
+export declare function fetchCdmConfig(url?: string): Promise<CdmConfig>;

package/dist/runtime/cdm-config.js

@@ -0,0 +1 @@
+import{getEnv as n}from"../env.js";export const DEFAULT_CDM_URL="https://config.blocksnetwork.functions.pdx1.aws.int.ps.pn/config.json";export async function fetchCdmConfig(o){const t=o??n("BLOCKS_CDM_URL")??DEFAULT_CDM_URL,s=await fetch(t);if(!s.ok)throw new Error(`CDM config fetch failed: ${s.status} ${s.statusText}`);const r=await s.json();if(!r.playground?.publishKey||!r.playground?.subscribeKey)throw new Error("CDM config missing playground keys");if(!r.network?.publishKey||!r.network?.subscribeKey)throw new Error("CDM config missing network keys");return r}

package/dist/runtime/channel-manager.d.ts

@@ -0,0 +1,125 @@
+/**
+ * ChannelManager - Centralized channel naming utility for agent-name sharding.
+ *
+ * Channel topology (org-scoped with 3-level constraint):
+ * - u.{orgId}.{taskId}             - Org-scoped task events (progress, artifacts, terminal, logs)
+ * - agent.{agentName}.control      - Control plane per agent name
+ * - obs.{agentName}.log            - Agent-level observability
+ *
+ * Registry channels (App Context membership indexes):
+ * - registry.all                   - All agents (membership index)
+ * - registry.public                - Public agents (membership index)
+ * - registry.private               - Private agents (membership index)
+ * - registry.skill.{skill}         - Agents with specific skill (membership index)
+ * - registry.log                   - Audit log channel (pub/sub with history)
+ *
+ * App Context (channel metadata, not pub/sub):
+ * - uuid:{agentName}               - Agent card stored as User Object
+ *
+ * All channels respect PubNub's 3-level maximum depth constraint.
+ * Subscribe filters are used for agent-name scoping on task channels.
+ */
+/**
+ * Registry "all" channel - membership index for all agents.
+ * Format: registry.all
+ */
+export declare const registryAllChannel: () => string;
+/**
+ * Registry skill channel - membership index for agents with a skill.
+ * Format: registry.skill.{skill}
+ *
+ * Skill slugs are normalized: lowercase, alphanumeric + `.` or `_`.
+ */
+export declare const registrySkillChannel: (skill: string) => string;
+/**
+ * Registry visibility channel - membership index for public/private agents.
+ * Format: registry.public or registry.private
+ */
+export declare const registryVisibilityChannel: (isPublic: boolean) => string;
+/**
+ * Registry audit log channel - pub/sub channel for registry change events.
+ * Format: registry.log
+ */
+export declare const registryLogChannel: () => string;
+/**
+ * Normalize a skill string to a stable slug.
+ * - Lowercase
+ * - Replace non-alphanumeric characters (except `.` and `_`) with `_`
+ * - Collapse multiple underscores
+ *
+ * Examples:
+ * - "image-generation" -> "image_generation"
+ * - "text.embeddings" -> "text.embeddings"
+ * - "Image Generation" -> "image_generation"
+ */
+export declare const normalizeSkillSlug: (skill: string) => string;
+/**
+ * Validates that an owner ID is not a reserved prefix.
+ */
+export declare function validateOwnerId(ownerId: string): boolean;
+export interface ChannelManagerOptions {
+    agentName?: string;
+}
+export declare class ChannelManager {
+    private readonly agentName;
+    constructor(opts?: ChannelManagerOptions);
+    getAgentName(): string;
+    /**
+     * Org-scoped task channel.
+     * All task events (progress, artifacts, terminal, logs) publish here.
+     * Format: u.{orgId}.{taskId} (3 levels)
+     */
+    taskChannel(taskId: string, orgId: string): string;
+    /**
+     * Control channel for agent.
+     * Format: agent.{agentName}.control (3 levels)
+     */
+    controlChannel(agentName?: string): string;
+    /**
+     * Agent-level observability channel.
+     * Format: obs.{agentName}.log (3 levels)
+     */
+    obsChannel(agentName?: string): string;
+    /**
+     * Wildcard pattern for org's task channels (for PAM grants).
+     * Format: u.{orgId}.* (grants access to all tasks for this org)
+     */
+    userTaskPattern(orgId: string): string;
+    /**
+     * Wildcard pattern for agent channels.
+     * Format: agent.{agentName}.* (for PAM grants)
+     */
+    agentWildcard(agentName?: string): string;
+    /**
+     * Stream data channel for an agent name and stream ID.
+     * Format: stream.{agentName}.{streamId} (3 levels).
+     *
+     * `streamId` is always SDK-derived, never caller-supplied:
+     * - Dedicated-affinity streams: `{taskId}-{counter}` (per-task,
+     *   counter increments per createStream() call within the task).
+     * - Shared-affinity streams: the card-declared key (constant
+     *   across tasks by design).
+     */
+    streamChannel(streamId: string, agentName?: string): string;
+    /**
+     * Wildcard pattern for all stream channels of an agent.
+     * Format: stream.{agentName}.* (for PAM grants)
+     */
+    streamWildcard(agentName?: string): string;
+}
+export declare const createChannelManager: (agentName: string) => ChannelManager;
+/**
+ * Org-scoped task channel (standalone function).
+ * Format: u.{orgId}.{taskId}
+ */
+export declare const taskChannel: (taskId: string, orgId: string) => string;
+/**
+ * Wildcard pattern for org's task channels (standalone function).
+ * Format: u.{orgId}.*
+ */
+export declare const userTaskPattern: (orgId: string) => string;
+/**
+ * Stream data channel (standalone function).
+ * Format: stream.{agentName}.{streamId}
+ */
+export declare const streamChannel: (agentName: string, streamId: string) => string;

package/dist/runtime/channel-manager.js

@@ -0,0 +1 @@
+export const registryAllChannel=()=>"registry.all";export const registrySkillChannel=r=>`registry.skill.${normalizeSkillSlug(r)}`;export const registryVisibilityChannel=r=>r?"registry.public":"registry.private";export const registryLogChannel=()=>"registry.log";export const normalizeSkillSlug=r=>r.toLowerCase().replace(/[^a-z0-9._]/g,"_").replace(/_+/g,"_").replace(/^_|_$/g,"");const r=["agent","obs","sys","u","anonymous","system","stream"];export function validateOwnerId(e){return!(!e||"string"!=typeof e)&&!r.includes(e.toLowerCase())}export class ChannelManager{constructor(r={}){if(!r.agentName)throw new Error("agentName is required for ChannelManager");this.agentName=r.agentName}getAgentName(){return this.agentName}taskChannel(r,e){if(!e)throw new Error("orgId required for task channel");if(!r)throw new Error("taskId required for task channel");return`u.${e}.${r}`}controlChannel(r){return`agent.${r??this.agentName}.control`}obsChannel(r){return`obs.${r??this.agentName}.log`}userTaskPattern(r){if(!r)throw new Error("orgId required for user task pattern");return`u.${r}.*`}agentWildcard(r){return`agent.${r??this.agentName}.*`}streamChannel(r,e){if(!r)throw new Error("streamId required for stream channel");return`stream.${e??this.agentName}.${r}`}streamWildcard(r){return`stream.${r??this.agentName}.*`}}export const createChannelManager=r=>new ChannelManager({agentName:r});export const taskChannel=(r,e)=>{if(!e)throw new Error("orgId required for task channel");if(!r)throw new Error("taskId required for task channel");return`u.${e}.${r}`};export const userTaskPattern=r=>{if(!r)throw new Error("orgId required for user task pattern");return`u.${r}.*`};export const streamChannel=(r,e)=>{if(!r)throw new Error("agentName required for stream channel");if(!e)throw new Error("streamId required for stream channel");return`stream.${r}.${e}`};

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

@@ -0,0 +1,112 @@
+/**
+ * ConsumerAuth -- consumer-side token acquisition and transparent refresh.
+ *
+ * Implements AuthProvider with three token acquisition modes:
+ *   Mode 1 (apiKey): exchange API key for consumer JWT via backend
+ *   Mode 2 (tokenEndpoint): POST to customer-owned proxy endpoint
+ *   Mode 3 (tokenProvider): call developer-supplied async function
+ *
+ * Proactive refresh at 80% TTL with exponential backoff on failure.
+ * Reactive refresh on 401 via onAuthFailure() with Promise dedup.
+ */
+import type { AuthProvider } from './auth-provider.js';
+/** Result from any token acquisition call. */
+export interface TokenResult {
+    token: string;
+    expiresIn: number;
+    userId?: string;
+}
+/**
+ * Credentials mode for the fetch call to a token endpoint.
+ *
+ * Mirrors the DOM/undici `RequestCredentials` union. Inlined here so the
+ * Node SDK's TypeScript configuration (no `"DOM"` lib) can reference the
+ * type without depending on the DOM ambient typings.
+ */
+export type TokenEndpointCredentials = 'omit' | 'same-origin' | 'include';
+/**
+ * Configuration for Mode 2 (token endpoint) token acquisition.
+ *
+ * Accepts either a bare URL string (the legacy form) or a config object
+ * with fetch-init overrides (`credentials`, `headers`, `body`). The config
+ * form is additive: SDK defaults (`method: 'POST'`, `Content-Type: application/json`,
+ * empty-object body) still apply; supplied fields override the defaults.
+ *
+ * The `body` value (when provided) is passed through `JSON.stringify`, so it
+ * must be JSON-serializable.
+ */
+export type TokenEndpointConfig = string | {
+    url: string;
+    credentials?: TokenEndpointCredentials;
+    headers?: Record<string, string>;
+    body?: unknown;
+};
+/** Options for constructing a ConsumerAuth instance. */
+export interface ConsumerAuthOptions {
+    apiKey?: string;
+    tokenEndpoint?: TokenEndpointConfig;
+    tokenProvider?: () => Promise<TokenResult>;
+    baseUrl?: string;
+    onAuthError?: (error: Error) => void;
+}
+export declare class ConsumerAuth implements AuthProvider {
+    private readonly _apiKey?;
+    private readonly _tokenEndpoint?;
+    private readonly _tokenProvider?;
+    private readonly _baseUrl;
+    private readonly _onAuthError?;
+    private _token;
+    private _refreshToken;
+    private _userId;
+    private _expiresIn;
+    private _destroyed;
+    private _refreshTimer;
+    private _refreshPromise;
+    constructor(options: ConsumerAuthOptions);
+    /**
+     * Acquire the initial token. Must be called before any other method.
+     */
+    init(): Promise<void>;
+    getAuthHeader(): string | null;
+    getUserId(): string | null;
+    /**
+     * Reactive refresh triggered by a 401 response. Returns true if a new
+     * token was acquired. Concurrent callers share a single in-flight
+     * refresh via Promise dedup.
+     */
+    onAuthFailure(): Promise<boolean>;
+    /**
+     * Stop proactive refresh timer. Does NOT clear the token -- active
+     * sessions can still use the last-known token for its remaining TTL.
+     */
+    destroy(): void;
+    private _initApiKey;
+    private _refreshApiKey;
+    private _initTokenEndpoint;
+    /**
+     * Mode-2 token-endpoint traffic goes to a customer-owned proxy, not the
+     * Blocks backend, so `X-Write-Affinity` is not exchanged in either
+     * direction: echoing it outbound would leak internal routing state to a
+     * third party, and capturing it inbound would let the proxy dictate this
+     * SDK's DB routing. Affinity lives on SDK -> Blocks calls only.
+     */
+    private _fetchTokenEndpoint;
+    private _initTokenProvider;
+    private _applyTokenResult;
+    /**
+     * Perform a single refresh attempt based on the active mode.
+     */
+    private _refreshOnce;
+    /**
+     * Deduplicated refresh: only one concurrent refresh runs at a time.
+     * Additional callers share the in-flight Promise.
+     */
+    private _doRefreshDedup;
+    /**
+     * Schedule proactive refresh at 80% of expiresIn. On failure, retry
+     * with exponential backoff (max 3 retries). On permanent failure,
+     * call onAuthError and stop scheduling.
+     */
+    private _scheduleRefresh;
+    private _proactiveRefreshWithRetry;
+}

package/dist/runtime/consumer-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";const i="API_KEY_INVALID";export class ConsumerAuth{constructor(e){this._token=null,this._refreshToken=null,this._userId=null,this._expiresIn=0,this._destroyed=!1,this._refreshTimer=null,this._refreshPromise=null,this._apiKey=e.apiKey,this._tokenEndpoint=e.tokenEndpoint,this._tokenProvider=e.tokenProvider,this._baseUrl=(e.baseUrl??"").replace(/\/+$/,""),this._onAuthError=e.onAuthError}async init(){if(this._apiKey)await this._initApiKey();else if(this._tokenEndpoint)await this._initTokenEndpoint();else{if(!this._tokenProvider)throw new Error("ConsumerAuth requires one of: apiKey, tokenEndpoint, or tokenProvider");await this._initTokenProvider()}this._scheduleRefresh()}getAuthHeader(){return this._token?`Bearer ${this._token}`:null}getUserId(){return this._userId}async onAuthFailure(){return!this._destroyed&&this._doRefreshDedup()}destroy(){this._destroyed=!0,this._refreshTimer&&(clearTimeout(this._refreshTimer),this._refreshTimer=null)}async _initApiKey(){const i=`${this._baseUrl}/api/v1/auth/agent/consumer-token`,n={"Content-Type":"application/json",[t]:e};s(n);const o=await fetch(i,{method:"POST",headers:n,body:JSON.stringify({apiKey:this._apiKey})});if(r(o.headers),!o.ok){const e=await o.text().catch(()=>"");throw new Error(`consumer-token failed: HTTP ${o.status}${e?` ${e}`:""}`)}const h=await o.json();this._token=h.accessToken,this._refreshToken=h.refreshToken,this._expiresIn=h.expiresIn,this._userId=h.userId}async _refreshApiKey(){const e=`${this._baseUrl}/api/v1/auth/agent/refresh`,t={Authorization:`Bearer ${this._apiKey}`,"Content-Type":"application/json"};s(t);const n=await fetch(e,{method:"POST",headers:t,body:JSON.stringify({refreshToken:this._refreshToken})});if(r(n.headers),!n.ok){const e=await n.json().catch(()=>({}));if("REFRESH_TOKEN_INVALID"===e.code)return void await this._initApiKey();if(e.code===i)throw new Error(`API key invalid or revoked: ${e.error??i}`);throw new Error(`token refresh failed: ${e.error??`HTTP ${n.status}`}`)}const o=await n.json();this._token=o.accessToken,this._refreshToken=o.refreshToken,"number"==typeof o.expiresIn&&(this._expiresIn=o.expiresIn)}async _initTokenEndpoint(){const e=await this._fetchTokenEndpoint();this._applyTokenResult(e)}async _fetchTokenEndpoint(){const e=this._tokenEndpoint,t="string"==typeof e,r=t?e:e.url;if("string"!=typeof r||!r)throw new Error("TokenEndpointConfig.url is required and must be a non-empty string");const s=t?void 0:e.credentials,i=t?{}:e.headers??{},n=t?{}:e.body??{},o={method:"POST",headers:{"Content-Type":"application/json",...i},body:JSON.stringify(n)};void 0!==s&&(o.credentials=s);const h=await fetch(r,o);if(!h.ok){const e=await h.text().catch(()=>"");throw new Error(`token endpoint failed: HTTP ${h.status}${e?` ${e}`:""}`)}return h.json()}async _initTokenProvider(){const e=await this._tokenProvider();this._applyTokenResult(e)}_applyTokenResult(e){this._token=e.token,this._expiresIn=e.expiresIn,void 0!==e.userId&&(this._userId=e.userId)}async _refreshOnce(){if(this._apiKey)await this._refreshApiKey();else if(this._tokenEndpoint){const e=await this._fetchTokenEndpoint();this._applyTokenResult(e)}else if(this._tokenProvider){const e=await this._tokenProvider();this._applyTokenResult(e)}}_doRefreshDedup(){return this._refreshPromise||(this._refreshPromise=this._refreshOnce().then(()=>(this._scheduleRefresh(),!0)).catch(()=>!1).finally(()=>{this._refreshPromise=null})),this._refreshPromise}_scheduleRefresh(){if(this._destroyed||this._expiresIn<=0)return;this._refreshTimer&&clearTimeout(this._refreshTimer);const e=1e3*this._expiresIn*.8;this._refreshTimer=setTimeout(()=>{this._refreshTimer=null,this._proactiveRefreshWithRetry(0)},e)}async _proactiveRefreshWithRetry(e){if(!this._destroyed)try{await this._refreshOnce(),this._scheduleRefresh()}catch(t){if(e<2){const t=Math.min(5e3*Math.pow(2,e),3e4);this._destroyed||(this._refreshTimer=setTimeout(()=>{this._refreshTimer=null,this._proactiveRefreshWithRetry(e+1)},t))}else{const e=t instanceof Error?t:new Error(String(t));this._onAuthError?this._onAuthError(e):console.warn("[ConsumerAuth] proactive refresh permanently failed:",e.message)}}}}