@sw4rm/js-sdk 0.3.0 → 0.5.0

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