@sw4rm/js-sdk 0.4.0 → 0.6.0

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.4.0",
+  "version": "0.6.0",
   "description": "SW4RM Agentic Protocol JavaScript/TypeScript SDK",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
@@ -14,7 +14,8 @@
     }
   },
   "scripts": {
-    "build": "npm run build:proto && npm run build:lib",
+    "build": "npm run build:proto && npm run build:lib && npm run copy:protos",
+    "copy:protos": "rm -rf protos && cp -r ../../protos protos",
     "example": "tsx",
     "build:proto": "npm run proto:js && npm run proto:ts",
     "build:lib": "npm run build:esm && npm run build:cjs && npm run build:types",
@@ -30,6 +31,7 @@
   },
   "files": [
     "dist",
+    "protos",
     "README.md",
     "LICENSE"
   ],

package/protos/activity.proto

@@ -0,0 +1,24 @@
+syntax = "proto3";
+
+package sw4rm.activity;
+
+message Artifact {
+  string negotiation_id = 1;
+  string kind = 2;       // contract|diff|decision|score|note
+  string version = 3;    // e.g., v3
+  string content_type = 4;
+  bytes content = 5;
+  string created_at = 6; // ISO-8601
+}
+
+message AppendArtifactRequest { Artifact artifact = 1; }
+message AppendArtifactResponse { bool ok = 1; string reason = 2; }
+
+message ListArtifactsRequest { string negotiation_id = 1; string kind = 2; }
+message ListArtifactsResponse { repeated Artifact items = 1; }
+
+service ActivityService {
+  rpc AppendArtifact(AppendArtifactRequest) returns (AppendArtifactResponse);
+  rpc ListArtifacts(ListArtifactsRequest) returns (ListArtifactsResponse);
+}
+

package/protos/common.proto

@@ -0,0 +1,141 @@
+syntax = "proto3";
+
+package sw4rm.common;
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/duration.proto";
+
+enum MessageType {
+  MESSAGE_TYPE_UNSPECIFIED = 0;
+  CONTROL = 1;
+  DATA = 2;
+  HEARTBEAT = 3;
+  NOTIFICATION = 4;
+  ACKNOWLEDGEMENT = 5;
+  HITL_INVOCATION = 6;
+  WORKTREE_CONTROL = 7;
+  NEGOTIATION = 8;
+  TOOL_CALL = 9;
+  TOOL_RESULT = 10;
+  TOOL_ERROR = 11;
+}
+
+enum AckStage {
+  ACK_STAGE_UNSPECIFIED = 0;
+  RECEIVED = 1;
+  READ = 2;
+  FULFILLED = 3;
+  REJECTED = 4;
+  FAILED = 5;
+  TIMED_OUT = 6;
+}
+
+enum ErrorCode {
+  ERROR_CODE_UNSPECIFIED = 0;
+  BUFFER_FULL = 1;
+  NO_ROUTE = 2;
+  ACK_TIMEOUT = 3;
+  AGENT_UNAVAILABLE = 4;
+  AGENT_SHUTDOWN = 5;
+  VALIDATION_ERROR = 6;
+  PERMISSION_DENIED = 7;
+  UNSUPPORTED_MESSAGE_TYPE = 8;
+  OVERSIZE_PAYLOAD = 9;
+  TOOL_TIMEOUT = 10;
+  PARTIAL_DELIVERY = 11; // reserved
+  FORCED_PREEMPTION = 12;
+  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;
+}
+
+enum AgentState {
+  AGENT_STATE_UNSPECIFIED = 0;
+  INITIALIZING = 1;
+  RUNNABLE = 2;
+  SCHEDULED = 3;
+  RUNNING = 4;
+  WAITING = 5;
+  WAITING_RESOURCES = 6;
+  SUSPENDED = 7;
+  RESUMED = 8;
+  COMPLETED = 9;
+  FAILED_STATE = 10;
+  SHUTTING_DOWN = 11;
+  RECOVERING = 12;
+}
+
+enum CommunicationClass {
+  COMM_CLASS_UNSPECIFIED = 0;
+  PRIVILEGED = 1;
+  STANDARD = 2;
+  BULK = 3;
+}
+
+enum DebateIntensity {
+  DEBATE_INTENSITY_UNSPECIFIED = 0;
+  LOWEST = 1;
+  LOW = 2;
+  MEDIUM = 3;
+  HIGH = 4;
+  HIGHEST = 5;
+}
+
+enum HitlReasonType {
+  HITL_REASON_UNSPECIFIED = 0;
+  CONFLICT = 1;
+  SECURITY_APPROVAL = 2;
+  TASK_ESCALATION = 3;
+  MANUAL_OVERRIDE = 4;
+  WORKTREE_OVERRIDE = 5;
+  DEBATE_DEADLOCK = 6;
+  TOOL_PRIVILEGE_ESCALATION = 7;
+  CONNECTOR_APPROVAL = 8;
+}
+
+enum EnvelopeState {
+  ENVELOPE_STATE_UNSPECIFIED = 0;
+  ENVELOPE_STATE_SENT = 1;
+  ENVELOPE_STATE_RECEIVED = 2;
+  ENVELOPE_STATE_READ = 3;
+  ENVELOPE_STATE_FULFILLED = 4;
+  ENVELOPE_STATE_REJECTED = 5;
+  ENVELOPE_STATE_FAILED = 6;
+  ENVELOPE_STATE_TIMED_OUT = 7;
+}
+
+message Envelope {
+  string message_id = 1;                // UUIDv4 per attempt
+  string idempotency_token = 2;         // stable across retries (optional)
+  string producer_id = 3;
+  string correlation_id = 4;
+  uint64 sequence_number = 5;
+  uint32 retry_count = 6;
+  MessageType message_type = 7;
+  string content_type = 8;              // e.g., application/json
+  uint64 content_length = 9;
+  string repo_id = 10;                  // optional
+  string worktree_id = 11;              // optional
+  string hlc_timestamp = 12;            // optional, string-form HLC
+  uint64 ttl_ms = 13;                   // optional
+  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 {
+  string ack_for_message_id = 1;
+  AckStage ack_stage = 2;
+  ErrorCode error_code = 3;
+  string note = 4;
+}
+
+message Empty {}

package/protos/connector.proto

@@ -0,0 +1,29 @@
+syntax = "proto3";
+
+package sw4rm.connector;
+
+message ToolDescriptor {
+  string tool_name = 1;
+  string input_schema = 2;   // JSON Schema or URL
+  string output_schema = 3;
+  bool idempotent = 4;
+  bool needs_worktree = 5;
+  uint32 default_timeout_s = 6;
+  uint32 max_concurrency = 7;
+  string side_effects = 8;   // "filesystem","network", etc.
+}
+
+message ProviderRegisterRequest {
+  string provider_id = 1;
+  repeated ToolDescriptor tools = 2;
+}
+
+message ProviderRegisterResponse { bool ok = 1; string reason = 2; }
+
+message DescribeToolsRequest { string provider_id = 1; }
+message DescribeToolsResponse { repeated ToolDescriptor tools = 1; }
+
+service ConnectorService {
+  rpc RegisterProvider(ProviderRegisterRequest) returns (ProviderRegisterResponse);
+  rpc DescribeTools(DescribeToolsRequest) returns (DescribeToolsResponse);
+}

package/protos/handoff.proto

@@ -0,0 +1,105 @@
+// SW4RM Protocol - Handoff Proto Definition
+// Namespace Convention: sw4rm.{service} (e.g., sw4rm.handoff)
+// See: docs/IMPLEMENTATION_PLAN.md Phase 1.1 for namespace standards.
+
+syntax = "proto3";
+
+package sw4rm.handoff;
+
+import "common.proto";
+import "google/protobuf/duration.proto";
+
+enum HandoffStatus {
+  HANDOFF_STATUS_UNSPECIFIED = 0;
+  PENDING = 1;
+  ACCEPTED = 2;
+  REJECTED = 3;
+  COMPLETED = 4;
+  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;
+  string to_agent = 3;
+  string reason = 4;
+  bytes context_snapshot = 5;
+  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 {
+  string request_id = 1;
+  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 {
+  string agent_id = 1;
+}
+
+message GetPendingHandoffsResponse {
+  repeated HandoffRequest pending_requests = 1;
+}
+
+message CompleteHandoffRequest {
+  string request_id = 1;
+  HandoffStatus status = 2;
+}
+
+message CompleteHandoffResponse {
+  bool success = 1;
+  string message = 2;
+}
+
+service HandoffService {
+  rpc RequestHandoff(HandoffRequest) returns (sw4rm.common.Empty);
+  rpc AcceptHandoff(HandoffResponse) returns (sw4rm.common.Empty);
+  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/hitl.proto

@@ -0,0 +1,23 @@
+syntax = "proto3";
+
+package sw4rm.hitl;
+
+import "common.proto";
+
+message HitlInvocation {
+  sw4rm.common.HitlReasonType reason_type = 1;
+  bytes context = 2;             // JSON or protobuf, see content_type in envelope
+  repeated string proposed_actions = 3;
+  int32 priority = 4;
+}
+
+message HitlDecision {
+  string action = 1;
+  bytes decision_payload = 2;
+  string rationale = 3;
+}
+
+service HitlService {
+  // Invocation is carried in Envelope.payload; this service handles the decision side.
+  rpc Decide(HitlInvocation) returns (HitlDecision);
+}

package/protos/logging.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+package sw4rm.logging;
+
+import "google/protobuf/timestamp.proto";
+
+message LogEvent {
+  google.protobuf.Timestamp ts = 1;
+  string correlation_id = 2;
+  string agent_id = 3;
+  string event_type = 4;
+  string level = 5; // INFO|WARN|ERROR
+  string details_json = 6;
+}
+
+message IngestResponse { bool ok = 1; }
+
+service LoggingService {
+  rpc Ingest(LogEvent) returns (IngestResponse);
+}

package/protos/negotiation.proto

@@ -0,0 +1,57 @@
+syntax = "proto3";
+
+package sw4rm.negotiation;
+
+import "common.proto";
+import "google/protobuf/duration.proto";
+
+message NegotiationOpen {
+  string negotiation_id = 1;
+  string correlation_id = 2;
+  string topic = 3;
+  repeated string participants = 4;
+  sw4rm.common.DebateIntensity intensity = 5;
+  google.protobuf.Duration debate_timeout = 6;
+}
+
+message Proposal {
+  string negotiation_id = 1;
+  string from_agent = 2;
+  string content_type = 3;
+  bytes payload = 4; // schema/proto/text as declared
+}
+
+message CounterProposal {
+  string negotiation_id = 1;
+  string from_agent = 2;
+  string content_type = 3;
+  bytes payload = 4;
+}
+
+message Evaluation {
+  string negotiation_id = 1;
+  string from_agent = 2;
+  double confidence_score = 3; // optional; 0 if absent
+  string notes = 4;
+}
+
+message Decision {
+  string negotiation_id = 1;
+  string decided_by = 2; // "consensus"|"hitl"|"policy"
+  string content_type = 3;
+  bytes result = 4;
+}
+
+message AbortRequest {
+  string negotiation_id = 1;
+  string reason = 2;
+}
+
+service NegotiationService {
+  rpc Open(NegotiationOpen) returns (sw4rm.common.Empty);
+  rpc Propose(Proposal) returns (sw4rm.common.Empty);
+  rpc Counter(CounterProposal) returns (sw4rm.common.Empty);
+  rpc Evaluate(Evaluation) returns (sw4rm.common.Empty);
+  rpc Decide(Decision) returns (sw4rm.common.Empty);
+  rpc Abort(AbortRequest) returns (sw4rm.common.Empty);
+}