@sw4rm/js-sdk 0.4.0 → 0.5.0

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,134 @@
+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;
+  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
+}
+
+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,63 @@
+// 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;
+}
+
+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;
+}
+
+message HandoffResponse {
+  string request_id = 1;
+  bool accepted = 2;
+  string accepting_agent = 3;
+  string rejection_reason = 4;
+}
+
+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);
+}

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);
+}

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;
+}