@sw4rm/js-sdk 0.5.0 → 0.6.0

package/dist/types/runtime/cancellation.d.ts

@@ -0,0 +1,41 @@
+import { ErrorCode } from '../internal/errorMapping.js';
+export declare const MIN_GRACE_PERIOD_MS = 5000;
+export type CancellationMetadataValue = string | number | boolean | null;
+export type CancellationMetadata = Record<string, CancellationMetadataValue>;
+export interface CancelDelegationRequest {
+    correlationId: string;
+    reason?: string;
+    gracePeriodMs?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface CancelDelegationResponse {
+    acknowledged: boolean;
+    correlationId: string;
+    gracePeriodMs: number;
+    message: string;
+    metadata: CancellationMetadata;
+}
+export interface CancellationFlag {
+    cancelled: boolean;
+    gracePeriodMs: number;
+    cancelTimeMs: number;
+    metadata: CancellationMetadata;
+}
+export interface CancellationManagerOptions {
+    nowMsFn?: () => number;
+}
+export declare class CancellationValidationError extends Error {
+    constructor(message: string);
+}
+export declare class CancellationManager {
+    readonly childDelegations: Map<string, Set<string>>;
+    readonly cancellationFlags: Map<string, CancellationFlag>;
+    private readonly nowMs;
+    constructor(options?: CancellationManagerOptions);
+    registerChildDelegation(parentCorrelationId: string, childCorrelationId: string): void;
+    handleCancelDelegation(cancel: CancelDelegationRequest): CancelDelegationResponse;
+    isCancelled(correlationId: string): boolean;
+    isGraceExpired(correlationId: string, nowMs?: number): boolean;
+    forcedPreemptionErrorCode(correlationId: string, nowMs?: number): ErrorCode;
+    collectForcedPreemptions(correlationIds: Iterable<string>, nowMs?: number): Set<string>;
+}

package/dist/types/runtime/delegation.d.ts

@@ -0,0 +1,20 @@
+import { type BudgetEnvelope, type HandoffRequest, type HandoffResponse, type SwarmDelegationPolicy } from '../clients/handoff.js';
+export declare const RETRY_AFTER_JITTER_RATIO = 0.2;
+export declare const DEFAULT_EFFECTIVE_MAX_REDIRECTS = 2;
+export interface DelegateToSwarmOptions {
+    sendHandoffFn: (request: HandoffRequest) => Promise<HandoffResponse> | HandoffResponse;
+    fromAgent: string;
+    toAgent: string;
+    reason: string;
+    budget: BudgetEnvelope;
+    delegationPolicy?: SwarmDelegationPolicy;
+    requestId?: string;
+    contextSnapshot?: Uint8Array;
+    capabilitiesRequired?: string[];
+    priority?: number;
+    timeoutMs?: number;
+    nowMsFn?: () => number;
+    sleepMsFn?: (milliseconds: number) => Promise<void> | void;
+    randUniformFn?: (low: number, high: number) => number;
+}
+export declare function delegateToSwarm(options: DelegateToSwarmOptions): Promise<HandoffResponse>;

package/dist/types/runtime/gateway.d.ts

@@ -0,0 +1,80 @@
+import type { HandoffRequest, HandoffResponse } from '../clients/handoff.js';
+export declare const REGISTRATION_TYPE_STANDARD_AGENT = 1;
+export declare const REGISTRATION_TYPE_SWARM_GATEWAY = 2;
+export declare const AGENT_STATE_INITIALIZING = 1;
+export declare const AGENT_STATE_RUNNING = 4;
+export declare const AGENT_STATE_FAILED = 10;
+export declare const AGENT_STATE_SHUTTING_DOWN = 11;
+export declare const DEFAULT_PEER_LIVENESS_THRESHOLD_MS = 30000;
+export declare const NON_SERVING_AGENT_STATES: Set<number>;
+export interface GatewayPeerDescriptor {
+    agentId: string;
+    registrationType: number;
+    capabilities: string[];
+}
+export interface PeerRuntimeState {
+    state: number;
+    lastHeartbeatMs: number;
+    cooldownUntilMs: number;
+}
+export interface PeerSelectorOptions {
+    localAgentId: string;
+    localCapabilities: string[];
+    nowMsFn?: () => number;
+    peerHealthFn?: (peer: GatewayPeerDescriptor) => boolean;
+    livenessThresholdMs?: number;
+}
+export interface UpdatePeerRuntimeStateOptions {
+    state?: number;
+    lastHeartbeatMs?: number;
+    cooldownUntilMs?: number;
+}
+export interface RecordPeerOverloadedOptions {
+    retryAfterMs?: number;
+    localCooldownMs?: number;
+}
+export interface GatewayRedirectEmitterOptions {
+    agentId: string;
+    capabilities?: string[];
+    retryAfterMs?: number;
+    peerDescriptors?: GatewayPeerDescriptor[];
+    peerHealthFn?: (peer: GatewayPeerDescriptor) => boolean;
+    nowMsFn?: () => number;
+    peerLivenessThresholdMs?: number;
+}
+export declare class GatewayValidationError extends Error {
+    constructor(message: string);
+}
+export declare class PeerSelector {
+    private readonly localAgentId;
+    private readonly localCapabilities;
+    private readonly nowMs;
+    private readonly peerHealthFn;
+    private readonly livenessThresholdMs;
+    private peers;
+    private runtime;
+    private rrCursor;
+    constructor(options: PeerSelectorOptions);
+    setPeers(peers: GatewayPeerDescriptor[]): void;
+    updatePeerRuntimeState(agentId: string, options?: UpdatePeerRuntimeStateOptions): void;
+    touchPeerHeartbeat(agentId: string, options?: Pick<UpdatePeerRuntimeStateOptions, 'state'> & {
+        nowMs?: number;
+    }): void;
+    recordPeerOverloaded(agentId: string, options?: RecordPeerOverloadedOptions): void;
+    isEligible(peer: GatewayPeerDescriptor): boolean;
+    selectPeer(): string;
+    private ensureRuntime;
+    private isHealthy;
+}
+export declare class GatewayRedirectEmitter {
+    private readonly retryAfterMs;
+    private readonly peerSelector;
+    constructor(options: GatewayRedirectEmitterOptions);
+    setPeerDescriptors(peers: GatewayPeerDescriptor[]): void;
+    updatePeerRuntimeState(agentId: string, options?: UpdatePeerRuntimeStateOptions): void;
+    touchPeerHeartbeat(agentId: string, options?: Pick<UpdatePeerRuntimeStateOptions, 'state'> & {
+        nowMs?: number;
+    }): void;
+    recordPeerOverloaded(agentId: string, options?: RecordPeerOverloadedOptions): void;
+    emitOverloadedResponse(request: HandoffRequest): HandoffResponse;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sw4rm/js-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "SW4RM Agentic Protocol JavaScript/TypeScript SDK",
   "type": "module",
   "main": "./dist/cjs/index.cjs",

package/protos/common.proto

@@ -47,6 +47,10 @@ enum ErrorCode {
   TTL_EXPIRED = 13;
   DUPLICATE_DETECTED = 14;
   ALREADY_IN_PROGRESS = 15;
+  // SW4-004 Inter-Swarm Composition (values 16-19)
+  OVERLOADED = 16;
+  // SW4-005 Spillover Routing (values 20-23)
+  REDIRECT = 20;
   INTERNAL_ERROR = 99;
 }
 
@@ -122,6 +126,9 @@ message Envelope {
   google.protobuf.Timestamp timestamp = 14;
   bytes payload = 15;                    // serialized content per content_type
   EnvelopeState state = 16;              // lifecycle state of the envelope
+
+  // SW4-004 Inter-Swarm Composition (fields 100-109)
+  string parent_correlation_id = 100;    // set on first envelope crossing a swarm boundary
 }
 
 message Ack {

package/protos/handoff.proto

@@ -18,6 +18,35 @@ enum HandoffStatus {
   EXPIRED = 5;
 }
 
+// SW4-004 Inter-Swarm Composition
+message BudgetEnvelope {
+  uint64 token_budget_remaining = 1;    // combined LLM input+output tokens
+  uint64 wall_time_remaining_ms = 2;
+  uint64 deadline_epoch_ms = 3;
+  uint32 current_depth = 4;
+  uint32 max_delegation_depth = 5;
+}
+
+message SwarmDelegationPolicy {
+  uint32 max_retries_on_overloaded = 1;
+  uint64 initial_backoff_ms = 2;
+  double backoff_multiplier = 3;
+  uint64 max_backoff_ms = 4;
+  bool allow_spillover_routing = 5;     // permits redirect to equivalent peer gateway
+  uint32 max_redirects = 6;              // SW4-005 redirect chain limit
+}
+
+message CancelDelegation {
+  string correlation_id = 1;           // identifies the delegation to cancel
+  string reason = 2;                   // human-readable cancellation reason
+  uint64 grace_period_ms = 3;         // time for cleanup before forced termination (min 5000ms)
+}
+
+message CancelDelegationResponse {
+  bool acknowledged = 1;
+  string message = 2;
+}
+
 message HandoffRequest {
   string request_id = 1;
   string from_agent = 2;
@@ -27,6 +56,10 @@ message HandoffRequest {
   repeated string capabilities_required = 6;
   int32 priority = 7;
   google.protobuf.Duration timeout = 8;
+
+  // SW4-004 Inter-Swarm Composition (fields 100-109)
+  BudgetEnvelope budget = 100;
+  SwarmDelegationPolicy delegation_policy = 101;
 }
 
 message HandoffResponse {
@@ -34,6 +67,13 @@ message HandoffResponse {
   bool accepted = 2;
   string accepting_agent = 3;
   string rejection_reason = 4;
+
+  // SW4-004 Inter-Swarm Composition (fields 100-109)
+  sw4rm.common.ErrorCode rejection_code = 100;
+  uint64 retry_after_ms = 101;
+
+  // SW4-005 Spillover Routing (fields 110-119)
+  string redirect_to_agent_id = 110;
 }
 
 message GetPendingHandoffsRequest {
@@ -60,4 +100,6 @@ service HandoffService {
   rpc RejectHandoff(HandoffResponse) returns (sw4rm.common.Empty);
   rpc GetPendingHandoffs(GetPendingHandoffsRequest) returns (GetPendingHandoffsResponse);
   rpc CompleteHandoff(CompleteHandoffRequest) returns (CompleteHandoffResponse);
+  // SW4-004 Inter-Swarm Composition: cascading cancellation
+  rpc CancelDelegation(sw4rm.handoff.CancelDelegation) returns (CancelDelegationResponse);
 }

package/protos/registry.proto

@@ -5,6 +5,13 @@ package sw4rm.registry;
 import "google/protobuf/timestamp.proto";
 import "common.proto";
 
+// SW4-004 Inter-Swarm Composition
+enum RegistrationType {
+  REGISTRATION_TYPE_UNSPECIFIED = 0;
+  STANDARD_AGENT = 1;
+  SWARM_GATEWAY = 2;
+}
+
 message AgentDescriptor {
   string agent_id = 1;
   string name = 2;
@@ -14,6 +21,10 @@ message AgentDescriptor {
   repeated string modalities_supported = 6; // MIME types
   repeated string reasoning_connectors = 7; // URIs
   bytes public_key = 8; // optional
+
+  // SW4-004 Inter-Swarm Composition (fields 100-109)
+  RegistrationType registration_type = 100;       // default STANDARD_AGENT
+  uint32 max_concurrent_delegations = 101;        // normative for SWARM_GATEWAY, advisory for STANDARD_AGENT
 }
 
 message RegisterAgentRequest { AgentDescriptor agent = 1; }