@sw4rm/js-sdk 0.4.0 → 0.6.0

package/protos/negotiation_room.proto

@@ -0,0 +1,220 @@
+// SW4RM Protocol - Negotiation Room Proto Definition
+// Namespace Convention: sw4rm.{service} (e.g., sw4rm.negotiation_room)
+// See: docs/IMPLEMENTATION_PLAN.md Phase 1.1 for namespace standards.
+
+syntax = "proto3";
+
+package sw4rm.negotiation_room;
+
+import "google/protobuf/timestamp.proto";
+
+// ArtifactType enum represents the category of artifact being negotiated
+// Maps to different stages of the workflow process
+enum ArtifactType {
+  ARTIFACT_TYPE_UNSPECIFIED = 0;
+  REQUIREMENTS = 1;
+  PLAN = 2;
+  CODE = 3;
+  DEPLOYMENT = 4;
+}
+
+// DecisionOutcome enum represents the final decision made by the coordinator
+// after aggregating critic votes and applying policy
+enum DecisionOutcome {
+  DECISION_OUTCOME_UNSPECIFIED = 0;
+  APPROVED = 1;
+  REVISION_REQUESTED = 2;
+  ESCALATED_TO_HITL = 3;
+}
+
+// NegotiationProposal represents a proposal for artifact evaluation in a negotiation room.
+// Submitted by a producer agent to request multi-agent review of an artifact.
+message NegotiationProposal {
+  // Category of artifact (requirements, plan, code, deployment)
+  ArtifactType artifact_type = 1;
+
+  // Unique identifier for this artifact
+  string artifact_id = 2;
+
+  // Agent ID of the producer submitting the artifact
+  string producer_id = 3;
+
+  // Binary artifact content (e.g., serialized JSON, code files)
+  bytes artifact = 4;
+
+  // MIME type or content type identifier
+  string artifact_content_type = 5;
+
+  // List of critic agent IDs requested for evaluation
+  repeated string requested_critics = 6;
+
+  // Identifier for the negotiation room session
+  string negotiation_room_id = 7;
+
+  // Timestamp when proposal was created
+  google.protobuf.Timestamp created_at = 8;
+}
+
+// NegotiationVote represents a critic's evaluation of an artifact.
+// Represents a single critic's assessment including numerical scoring,
+// qualitative feedback, and confidence level based on POMDP uncertainty.
+message NegotiationVote {
+  // Identifier of the artifact being evaluated
+  string artifact_id = 1;
+
+  // Agent ID of the critic providing this vote
+  string critic_id = 2;
+
+  // Numerical score from 0-10 (10 = excellent)
+  double score = 3;
+
+  // Confidence level from 0-1 (based on POMDP research)
+  double confidence = 4;
+
+  // Boolean indicating if artifact meets minimum criteria
+  bool passed = 5;
+
+  // List of identified strengths in the artifact
+  repeated string strengths = 6;
+
+  // List of identified weaknesses or concerns
+  repeated string weaknesses = 7;
+
+  // List of suggestions for improvement
+  repeated string recommendations = 8;
+
+  // Identifier for the negotiation room session
+  string negotiation_room_id = 9;
+
+  // Timestamp when vote was cast
+  google.protobuf.Timestamp voted_at = 10;
+}
+
+// AggregatedScore provides statistical aggregation of multiple critic votes.
+// Provides multiple views of the voting results including basic statistics
+// and confidence-weighted metrics for decision making.
+message AggregatedScore {
+  // Arithmetic mean of all scores
+  double mean = 1;
+
+  // Minimum score from any critic
+  double min_score = 2;
+
+  // Maximum score from any critic
+  double max_score = 3;
+
+  // Standard deviation of scores (measures consensus)
+  double std_dev = 4;
+
+  // Confidence-weighted mean (higher confidence votes weighted more)
+  double weighted_mean = 5;
+
+  // Number of votes included in aggregation
+  int32 vote_count = 6;
+}
+
+// NegotiationDecision represents the final decision on an artifact after critic evaluation.
+// Represents the coordinator's decision after aggregating all critic votes
+// and applying policy thresholds. Includes full audit trail of votes and reasoning.
+message NegotiationDecision {
+  // Identifier of the artifact that was evaluated
+  string artifact_id = 1;
+
+  // Final decision (approved, revision requested, escalated to HITL)
+  DecisionOutcome outcome = 2;
+
+  // Complete list of all critic votes considered
+  repeated NegotiationVote votes = 3;
+
+  // Statistical summary of the votes
+  AggregatedScore aggregated_score = 4;
+
+  // Version identifier of the policy used for decision
+  string policy_version = 5;
+
+  // Human-readable explanation of the decision
+  string reason = 6;
+
+  // Identifier for the negotiation room session
+  string negotiation_room_id = 7;
+
+  // Timestamp when decision was made
+  google.protobuf.Timestamp decided_at = 8;
+}
+
+// Request to submit a proposal to the negotiation room
+message SubmitProposalRequest {
+  NegotiationProposal proposal = 1;
+}
+
+// Response after submitting a proposal
+message SubmitProposalResponse {
+  string artifact_id = 1;
+  string negotiation_room_id = 2;
+}
+
+// Request to submit a vote for an artifact
+message SubmitVoteRequest {
+  NegotiationVote vote = 1;
+}
+
+// Response after submitting a vote
+message SubmitVoteResponse {
+  string artifact_id = 1;
+  string critic_id = 2;
+}
+
+// Request to get all votes for an artifact
+message GetVotesRequest {
+  string artifact_id = 1;
+  string negotiation_room_id = 2;
+}
+
+// Response containing all votes for an artifact
+message GetVotesResponse {
+  repeated NegotiationVote votes = 1;
+  int32 vote_count = 2;
+}
+
+// Request to get the decision for an artifact
+message GetDecisionRequest {
+  string artifact_id = 1;
+  string negotiation_room_id = 2;
+}
+
+// Response containing the decision for an artifact
+message GetDecisionResponse {
+  NegotiationDecision decision = 1;
+}
+
+// Request to wait for a decision (blocking call)
+message WaitForDecisionRequest {
+  string artifact_id = 1;
+  string negotiation_room_id = 2;
+  // Optional timeout in seconds
+  uint32 timeout_seconds = 3;
+}
+
+// Response for waiting on a decision
+message WaitForDecisionResponse {
+  NegotiationDecision decision = 1;
+}
+
+// NegotiationRoomService provides RPC endpoints for the Negotiation Room pattern
+// enabling multi-agent artifact approval workflows
+service NegotiationRoomService {
+  // SubmitProposal allows a producer agent to submit an artifact for review
+  rpc SubmitProposal(SubmitProposalRequest) returns (SubmitProposalResponse);
+
+  // SubmitVote allows a critic agent to submit their evaluation of an artifact
+  rpc SubmitVote(SubmitVoteRequest) returns (SubmitVoteResponse);
+
+  // GetVotes retrieves all votes submitted for a specific artifact
+  rpc GetVotes(GetVotesRequest) returns (GetVotesResponse);
+
+  // GetDecision retrieves the final decision for an artifact (non-blocking)
+  rpc GetDecision(GetDecisionRequest) returns (GetDecisionResponse);
+
+  // WaitForDecision blocks until a decision is made for an artifact
+  rpc WaitForDecision(WaitForDecisionRequest) returns (WaitForDecisionResponse);
+}

package/protos/policy.proto

@@ -0,0 +1,55 @@
+syntax = "proto3";
+
+package sw4rm.policy;
+
+message NegotiationPolicy {
+  uint32 max_rounds = 1;
+  float score_threshold = 2;      // 0..1
+  float diff_tolerance = 3;       // 0..1
+  uint64 round_timeout_ms = 4;
+  uint64 token_budget_per_round = 5;
+  uint64 total_token_budget = 6;  // optional 0=unset
+  uint32 oscillation_limit = 7;
+  message Hitl { string mode = 1; } // None|PauseBetweenRounds|PauseOnFinalAccept
+  Hitl hitl = 8;
+  message Scoring { bool require_schema_valid = 1; bool require_examples_pass = 2; float llm_weight = 3; }
+  Scoring scoring = 9;
+}
+
+message AgentPreferences {
+  // Same fields as NegotiationPolicy but advisory; scheduler clamps to guardrails
+  uint32 max_rounds = 1;
+  float score_threshold = 2;
+  float diff_tolerance = 3;
+  uint64 round_timeout_ms = 4;
+  uint64 token_budget_per_round = 5;
+  uint64 total_token_budget = 6;
+  uint32 oscillation_limit = 7;
+}
+
+message EffectivePolicy {
+  NegotiationPolicy policy = 1;                // derived authoritative policy
+  map<string, AgentPreferences> applied = 2; // per-agent clamped prefs (optional)
+}
+
+message PolicyProfile {
+  string name = 1;            // e.g., LOW/MEDIUM/HIGH
+  NegotiationPolicy policy = 2;
+}
+
+message DeltaSummary { float magnitude = 1; repeated string changed_paths = 2; }
+
+message EvaluationReport {
+  string from_agent = 1;
+  float deterministic_score = 2; // 0..1
+  float llm_confidence = 3;      // 0..1, optional 0 if absent
+  string notes = 4;
+  DeltaSummary delta = 5;
+}
+
+message DecisionReport {
+  string decided_by = 1;  // consensus|hitl|policy
+  float final_score = 2;
+  string rationale = 3;
+  string stop_reason = 4; // threshold_met|max_rounds|oscillation|budget|timeout
+}

package/protos/reasoning.proto

@@ -0,0 +1,41 @@
+syntax = "proto3";
+
+package sw4rm.reasoning;
+
+message ParallelismCheckRequest { string scope_a = 1; string scope_b = 2; }
+message ParallelismCheckResponse { double confidence_score = 1; string notes = 2; }
+
+message DebateEvaluateRequest {
+  string negotiation_id = 1;
+  string proposal_a = 2;
+  string proposal_b = 3;
+  string intensity = 4; // map from enum if needed
+}
+message DebateEvaluateResponse { double confidence_score = 1; string notes = 2; }
+
+service ReasoningProxy {
+  rpc CheckParallelism(ParallelismCheckRequest) returns (ParallelismCheckResponse);
+  rpc EvaluateDebate(DebateEvaluateRequest) returns (DebateEvaluateResponse);
+  rpc Summarize(SummarizeRequest) returns (SummarizeResponse);
+}
+
+message TextSegment {
+  string kind = 1;
+  string content = 2;
+  int64  seq = 3;
+  string at = 4;
+}
+
+message SummarizeRequest {
+  string session_id = 1;
+  repeated TextSegment segments = 2;
+  uint32 max_tokens = 3;
+  string mode = 4;
+}
+
+message SummarizeResponse {
+  string summary = 1;
+  uint32 tokens = 2;
+  double cost_cents = 3;
+  string model = 4;
+}

package/protos/registry.proto

@@ -0,0 +1,47 @@
+syntax = "proto3";
+
+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;
+  string description = 3; // ≤200 words
+  repeated string capabilities = 4;
+  sw4rm.common.CommunicationClass communication_class = 5;
+  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; }
+message RegisterAgentResponse { bool accepted = 1; string reason = 2; }
+
+message HeartbeatRequest {
+  string agent_id = 1;
+  sw4rm.common.AgentState state = 2;
+  map<string,string> health = 3;
+}
+message HeartbeatResponse { bool ok = 1; }
+
+message DeregisterAgentRequest { string agent_id = 1; string reason = 2; }
+message DeregisterAgentResponse { bool ok = 1; }
+
+service RegistryService {
+  rpc RegisterAgent(RegisterAgentRequest) returns (RegisterAgentResponse);
+  rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse);
+  rpc DeregisterAgent(DeregisterAgentRequest) returns (DeregisterAgentResponse);
+}

package/protos/router.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package sw4rm.router;
+
+import "common.proto";
+
+message SendMessageRequest { sw4rm.common.Envelope msg = 1; }
+message SendMessageResponse { bool accepted = 1; string reason = 2; }
+
+message StreamRequest { string agent_id = 1; }
+message StreamItem { sw4rm.common.Envelope msg = 1; }
+
+service RouterService {
+  rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
+  rpc StreamIncoming(StreamRequest) returns (stream StreamItem); // per-agent inbound stream
+}

package/protos/scheduler.proto

@@ -0,0 +1,52 @@
+syntax = "proto3";
+
+package sw4rm.scheduler;
+
+import "google/protobuf/duration.proto";
+import "common.proto";
+
+message SubmitTaskRequest {
+  string agent_id = 1;
+  string task_id = 2;
+  int32 priority = 3; // -19..20
+  bytes params = 4;
+  string content_type = 5;
+  string scope = 6; // resource scope descriptor
+}
+
+message SubmitTaskResponse { bool accepted = 1; string reason = 2; }
+
+message PreemptRequest {
+  string agent_id = 1;
+  string task_id = 2;
+  string reason = 3;
+}
+message PreemptResponse { bool enqueued = 1; }
+
+message ShutdownAgentRequest {
+  string agent_id = 1;
+  google.protobuf.Duration grace_period = 2;
+}
+message ShutdownAgentResponse { bool ok = 1; }
+
+message PollActivityBufferRequest { string agent_id = 1; }
+message ActivityEntry {
+  string task_id = 1;
+  string repo_id = 2;
+  string worktree_id = 3;
+  string branch = 4;
+  string description = 5;
+  string timestamp = 6;
+}
+message PollActivityBufferResponse { repeated ActivityEntry entries = 1; }
+
+message PurgeActivityRequest { string agent_id = 1; repeated string task_ids = 2; }
+message PurgeActivityResponse { uint32 purged = 1; }
+
+service SchedulerService {
+  rpc SubmitTask(SubmitTaskRequest) returns (SubmitTaskResponse);
+  rpc RequestPreemption(PreemptRequest) returns (PreemptResponse);
+  rpc ShutdownAgent(ShutdownAgentRequest) returns (ShutdownAgentResponse);
+  rpc PollActivityBuffer(PollActivityBufferRequest) returns (PollActivityBufferResponse);
+  rpc PurgeActivity(PurgeActivityRequest) returns (PurgeActivityResponse);
+}

package/protos/scheduler_policy.proto

@@ -0,0 +1,36 @@
+syntax = "proto3";
+
+package sw4rm.scheduler;
+
+import "policy.proto";
+
+message SetNegotiationPolicyRequest { sw4rm.policy.NegotiationPolicy policy = 1; }
+message SetNegotiationPolicyResponse { bool ok = 1; string reason = 2; }
+
+message GetNegotiationPolicyRequest {}
+message GetNegotiationPolicyResponse { sw4rm.policy.NegotiationPolicy policy = 1; }
+
+message SetPolicyProfilesRequest { repeated sw4rm.policy.PolicyProfile profiles = 1; }
+message SetPolicyProfilesResponse { bool ok = 1; string reason = 2; }
+
+message ListPolicyProfilesRequest {}
+message ListPolicyProfilesResponse { repeated sw4rm.policy.PolicyProfile profiles = 1; }
+
+message GetEffectivePolicyRequest { string negotiation_id = 1; }
+message GetEffectivePolicyResponse { sw4rm.policy.EffectivePolicy effective = 1; }
+
+message SubmitEvaluationRequest { string negotiation_id = 1; sw4rm.policy.EvaluationReport report = 2; }
+message SubmitEvaluationResponse { bool accepted = 1; string reason = 2; }
+
+message HitlActionRequest { string negotiation_id = 1; string action = 2; string rationale = 3; }
+message HitlActionResponse { bool ok = 1; string reason = 2; }
+
+service SchedulerPolicyService {
+  rpc SetNegotiationPolicy(SetNegotiationPolicyRequest) returns (SetNegotiationPolicyResponse);
+  rpc GetNegotiationPolicy(GetNegotiationPolicyRequest) returns (GetNegotiationPolicyResponse);
+  rpc SetPolicyProfiles(SetPolicyProfilesRequest) returns (SetPolicyProfilesResponse);
+  rpc ListPolicyProfiles(ListPolicyProfilesRequest) returns (ListPolicyProfilesResponse);
+  rpc GetEffectivePolicy(GetEffectivePolicyRequest) returns (GetEffectivePolicyResponse);
+  rpc SubmitEvaluation(SubmitEvaluationRequest) returns (SubmitEvaluationResponse);
+  rpc HitlAction(HitlActionRequest) returns (HitlActionResponse);
+}

package/protos/tool.proto

@@ -0,0 +1,47 @@
+syntax = "proto3";
+
+package sw4rm.tool;
+
+import "google/protobuf/duration.proto";
+
+message ExecutionPolicy {
+  google.protobuf.Duration timeout = 1;
+  uint32 max_retries = 2;
+  string backoff = 3; // "exponential", etc.
+  bool worktree_required = 4;
+  string network_policy = 5;     // e.g., "egress_restricted"
+  string privilege_level = 6;    // e.g., "default"
+  uint64 budget_cpu_ms = 7;
+  uint64 budget_wall_ms = 8;
+}
+
+message ToolCall {
+  string call_id = 1;
+  string tool_name = 2;
+  string provider_id = 3;
+  string content_type = 4;
+  bytes args = 5;
+  ExecutionPolicy policy = 6;
+  bool stream = 7;
+}
+
+message ToolFrame {
+  string call_id = 1;
+  uint64 frame_no = 2;
+  bool final = 3;
+  string content_type = 4;
+  bytes data = 5;
+  bytes summary = 6; // optional final summary
+}
+
+message ToolError {
+  string call_id = 1;
+  string error_code = 2;
+  string message = 3;
+}
+
+service ToolService {
+  rpc Call(ToolCall) returns (ToolFrame);                 // unary completion
+  rpc CallStream(ToolCall) returns (stream ToolFrame);    // streaming frames
+  rpc Cancel(ToolCall) returns (ToolError);               // best effort
+}

package/protos/workflow.proto

@@ -0,0 +1,116 @@
+// SW4RM Protocol - Workflow Proto Definition
+// Namespace Convention: sw4rm.{service} (e.g., sw4rm.workflow)
+// See: docs/IMPLEMENTATION_PLAN.md Phase 1.1 for namespace standards.
+
+syntax = "proto3";
+
+package sw4rm.workflow;
+
+import "google/protobuf/timestamp.proto";
+
+enum NodeStatus {
+  NODE_STATUS_UNSPECIFIED = 0;
+  PENDING = 1;      // Node waiting for dependencies
+  READY = 2;        // Node ready to execute
+  RUNNING = 3;      // Node currently executing
+  COMPLETED = 4;    // Node finished successfully
+  FAILED = 5;       // Node encountered an error
+  SKIPPED = 6;      // Node skipped due to conditional logic
+}
+
+enum TriggerType {
+  TRIGGER_TYPE_UNSPECIFIED = 0;
+  EVENT = 1;        // Triggered by specific events
+  SCHEDULE = 2;     // Triggered on a schedule (cron-like)
+  MANUAL = 3;       // Triggered by explicit user action
+  DEPENDENCY = 4;   // Triggered by dependency completion
+}
+
+message WorkflowNode {
+  string node_id = 1;                           // Unique identifier for this node
+  string agent_id = 2;                          // Identifier of the agent executing this node
+  repeated string dependencies = 3;             // Set of node_ids that must complete before this node runs
+  TriggerType trigger_type = 4;                 // How this node is triggered
+  map<string, string> input_mapping = 5;        // Maps workflow state keys to node input parameters
+  map<string, string> output_mapping = 6;       // Maps node output keys to workflow state keys
+  map<string, string> metadata = 7;             // Additional node configuration and context
+}
+
+message WorkflowDefinition {
+  string workflow_id = 1;                       // Unique identifier for this workflow
+  map<string, WorkflowNode> nodes = 2;          // Map of node_id to WorkflowNode
+  google.protobuf.Timestamp created_at = 3;    // When the workflow was created
+  map<string, string> metadata = 4;             // Additional workflow-level configuration
+}
+
+message NodeState {
+  string node_id = 1;                           // The node this state belongs to
+  NodeStatus status = 2;                        // Current execution status
+  google.protobuf.Timestamp started_at = 3;    // When node execution started
+  google.protobuf.Timestamp completed_at = 4;  // When node execution completed
+  string output = 5;                            // Output data from node execution (JSON string)
+  string error = 6;                             // Error information if node failed
+}
+
+message WorkflowState {
+  string workflow_id = 1;                       // Identifier of the workflow being executed
+  map<string, NodeState> node_states = 2;       // Map of node_id to NodeState for tracking execution
+  string workflow_data = 3;                     // Shared workflow data (JSON string)
+  google.protobuf.Timestamp started_at = 4;    // When the workflow execution started
+  google.protobuf.Timestamp completed_at = 5;  // When the workflow execution completed
+  map<string, string> metadata = 6;             // Additional runtime metadata
+}
+
+message CreateWorkflowRequest {
+  WorkflowDefinition definition = 1;
+}
+
+message CreateWorkflowResponse {
+  string workflow_id = 1;
+  bool success = 2;
+  string error = 3;
+}
+
+message StartWorkflowRequest {
+  string workflow_id = 1;
+  string workflow_data = 2;                     // Initial workflow data (JSON string)
+  map<string, string> metadata = 3;             // Runtime metadata
+}
+
+message StartWorkflowResponse {
+  string workflow_id = 1;
+  WorkflowState state = 2;
+  bool success = 3;
+  string error = 4;
+}
+
+message GetWorkflowStateRequest {
+  string workflow_id = 1;
+}
+
+message GetWorkflowStateResponse {
+  WorkflowState state = 1;
+  bool success = 2;
+  string error = 3;
+}
+
+message ResumeWorkflowRequest {
+  string workflow_id = 1;
+  string node_id = 2;
+  string workflow_data = 3;                     // Updated workflow data (JSON string)
+  map<string, string> metadata = 4;             // Runtime metadata
+}
+
+message ResumeWorkflowResponse {
+  string workflow_id = 1;
+  WorkflowState state = 2;
+  bool success = 3;
+  string error = 4;
+}
+
+service WorkflowService {
+  rpc CreateWorkflow(CreateWorkflowRequest) returns (CreateWorkflowResponse);
+  rpc StartWorkflow(StartWorkflowRequest) returns (StartWorkflowResponse);
+  rpc GetWorkflowState(GetWorkflowStateRequest) returns (GetWorkflowStateResponse);
+  rpc ResumeWorkflow(ResumeWorkflowRequest) returns (ResumeWorkflowResponse);
+}

package/protos/worktree.proto

@@ -0,0 +1,33 @@
+syntax = "proto3";
+
+package sw4rm.worktree;
+
+message BindRequest { string agent_id = 1; string repo_id = 2; string worktree_id = 3; }
+message BindResponse { bool ok = 1; string reason = 2; }
+
+message UnbindRequest { string agent_id = 1; }
+message UnbindResponse { bool ok = 1; }
+
+message SwitchRequest {
+  string agent_id = 1;
+  string target_worktree_id = 2;
+  bool requires_hitl = 3;
+}
+message SwitchApprove { string agent_id = 1; string target_worktree_id = 2; uint64 ttl_ms = 3; }
+message SwitchReject { string agent_id = 1; string reason = 2; }
+
+message StatusRequest { string agent_id = 1; }
+message StatusResponse {
+  string repo_id = 1;
+  string worktree_id = 2;
+  string state = 3; // UNBOUND|BOUND_HOME|SWITCH_PENDING|BOUND_NON_HOME|BIND_FAILED
+}
+
+service WorktreeService {
+  rpc Bind(BindRequest) returns (BindResponse);
+  rpc Unbind(UnbindRequest) returns (UnbindResponse);
+  rpc RequestSwitch(SwitchRequest) returns (StatusResponse);
+  rpc ApproveSwitch(SwitchApprove) returns (StatusResponse);
+  rpc RejectSwitch(SwitchReject) returns (StatusResponse);
+  rpc Status(StatusRequest) returns (StatusResponse);
+}