Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
api: define the agent sandbox connector interface
Antonio Ojea7abe3c30a38c
diff --git a/api/sam.pb.go b/api/sam.pb.goindex 3f1afa1b..6dd40d98 100644--- a/api/sam.pb.go+++ b/api/sam.pb.go@@ -1890,6 +1890,786 @@ func (x *TokenRevokeResponse) GetError() string {return ""}+// AgentSecret configures credential injection for one destination. It carries+// a path, never a value: secret material must not travel through this API.+type AgentSecret struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ Host string `protobuf:"bytes,1,opt,name=host,proto3" json:"host,omitempty"`+ Kind string `protobuf:"bytes,2,opt,name=kind,proto3" json:"kind,omitempty"` // bearer | basicauth | customheader+ HeaderName string `protobuf:"bytes,3,opt,name=header_name,json=headerName,proto3" json:"header_name,omitempty"` // customheader only+ ValuePath string `protobuf:"bytes,4,opt,name=value_path,json=valuePath,proto3" json:"value_path,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentSecret) Reset() {+ *x = AgentSecret{}+ mi := &file_api_sam_proto_msgTypes[27]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentSecret) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentSecret) ProtoMessage() {}++func (x *AgentSecret) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[27]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentSecret.ProtoReflect.Descriptor instead.+func (*AgentSecret) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{27}+}++func (x *AgentSecret) GetHost() string {+ if x != nil {+ return x.Host+ }+ return ""+}++func (x *AgentSecret) GetKind() string {+ if x != nil {+ return x.Kind+ }+ return ""+}++func (x *AgentSecret) GetHeaderName() string {+ if x != nil {+ return x.HeaderName+ }+ return ""+}++func (x *AgentSecret) GetValuePath() string {+ if x != nil {+ return x.ValuePath+ }+ return ""+}++// AgentEgress is deny-by-default. Patterns are matched against the destination+// name taken from the sandbox boundary, never against a resolved address.+type AgentEgress struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ Allow []string `protobuf:"bytes,1,rep,name=allow,proto3" json:"allow,omitempty"`+ Secrets []*AgentSecret `protobuf:"bytes,2,rep,name=secrets,proto3" json:"secrets,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentEgress) Reset() {+ *x = AgentEgress{}+ mi := &file_api_sam_proto_msgTypes[28]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentEgress) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentEgress) ProtoMessage() {}++func (x *AgentEgress) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[28]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentEgress.ProtoReflect.Descriptor instead.+func (*AgentEgress) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{28}+}++func (x *AgentEgress) GetAllow() []string {+ if x != nil {+ return x.Allow+ }+ return nil+}++func (x *AgentEgress) GetSecrets() []*AgentSecret {+ if x != nil {+ return x.Secrets+ }+ return nil+}++// AgentIngress declares that the agent serves a mesh service. The name is the+// service half of the mesh host the rest of the mesh dials (see api/names.go);+// port is where the agent listens inside its sandbox.+type AgentIngress struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ Type ServiceType `protobuf:"varint,1,opt,name=type,proto3,enum=sam.v1.ServiceType" json:"type,omitempty"`+ Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`+ Port uint32 `protobuf:"varint,3,opt,name=port,proto3" json:"port,omitempty"`+ Description string `protobuf:"bytes,4,opt,name=description,proto3" json:"description,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentIngress) Reset() {+ *x = AgentIngress{}+ mi := &file_api_sam_proto_msgTypes[29]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentIngress) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentIngress) ProtoMessage() {}++func (x *AgentIngress) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[29]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentIngress.ProtoReflect.Descriptor instead.+func (*AgentIngress) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{29}+}++func (x *AgentIngress) GetType() ServiceType {+ if x != nil {+ return x.Type+ }+ return ServiceType_SERVICE_TYPE_UNSPECIFIED+}++func (x *AgentIngress) GetName() string {+ if x != nil {+ return x.Name+ }+ return ""+}++func (x *AgentIngress) GetPort() uint32 {+ if x != nil {+ return x.Port+ }+ return 0+}++func (x *AgentIngress) GetDescription() string {+ if x != nil {+ return x.Description+ }+ return ""+}++// AgentBundle is everything the platform declares about one agent. Its+// canonical form is a YAML file in the agent's own state directory, so that a+// suspend/resume onto another host carries it with no extra machinery; this+// message is the transport mirror of that file.+type AgentBundle struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ Version string `protobuf:"bytes,1,opt,name=version,proto3" json:"version,omitempty"`+ // Canonical mesh identifier, without the "agent:" prefix. Dot-separated and+ // DNS-shaped; see api/agent.go for the rules and why they exist.+ AgentId string `protobuf:"bytes,2,opt,name=agent_id,json=agentId,proto3" json:"agent_id,omitempty"`+ // The platform's own identifier, verbatim, kept for audit because the+ // translation into agent_id is not always reversible.+ ExternalId string `protobuf:"bytes,3,opt,name=external_id,json=externalId,proto3" json:"external_id,omitempty"`+ // Path to the workload credential the platform already issues: a projected+ // Kubernetes service-account token, a pod certificate, or an SVID. It is+ // verified at admission against the platform's issuer and then translated+ // into agent facts, the same way OIDC claims are translated at node+ // enrollment. The scheduler needs no mesh credential of its own.+ CredentialPath string `protobuf:"bytes,4,opt,name=credential_path,json=credentialPath,proto3" json:"credential_path,omitempty"`+ Egress *AgentEgress `protobuf:"bytes,5,opt,name=egress,proto3" json:"egress,omitempty"`+ Ingress []*AgentIngress `protobuf:"bytes,6,rep,name=ingress,proto3" json:"ingress,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentBundle) Reset() {+ *x = AgentBundle{}+ mi := &file_api_sam_proto_msgTypes[30]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentBundle) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentBundle) ProtoMessage() {}++func (x *AgentBundle) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[30]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentBundle.ProtoReflect.Descriptor instead.+func (*AgentBundle) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{30}+}++func (x *AgentBundle) GetVersion() string {+ if x != nil {+ return x.Version+ }+ return ""+}++func (x *AgentBundle) GetAgentId() string {+ if x != nil {+ return x.AgentId+ }+ return ""+}++func (x *AgentBundle) GetExternalId() string {+ if x != nil {+ return x.ExternalId+ }+ return ""+}++func (x *AgentBundle) GetCredentialPath() string {+ if x != nil {+ return x.CredentialPath+ }+ return ""+}++func (x *AgentBundle) GetEgress() *AgentEgress {+ if x != nil {+ return x.Egress+ }+ return nil+}++func (x *AgentBundle) GetIngress() []*AgentIngress {+ if x != nil {+ return x.Ingress+ }+ return nil+}++// AgentAttachRequest admits an agent. It is idempotent on agent_id: resuming+// after a crash or a migration is another Attach, not a distinct operation.+type AgentAttachRequest struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ Bundle *AgentBundle `protobuf:"bytes,1,opt,name=bundle,proto3" json:"bundle,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentAttachRequest) Reset() {+ *x = AgentAttachRequest{}+ mi := &file_api_sam_proto_msgTypes[31]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentAttachRequest) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentAttachRequest) ProtoMessage() {}++func (x *AgentAttachRequest) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[31]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentAttachRequest.ProtoReflect.Descriptor instead.+func (*AgentAttachRequest) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{31}+}++func (x *AgentAttachRequest) GetBundle() *AgentBundle {+ if x != nil {+ return x.Bundle+ }+ return nil+}++type AgentAttachResponse struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ // Sandbox boundary endpoints to wire into the sandbox: SOCKS5 for guest to+ // host, and a reverse channel for host to guest that is empty when the+ // bundle declares no ingress.+ EgressSocket string `protobuf:"bytes,1,opt,name=egress_socket,json=egressSocket,proto3" json:"egress_socket,omitempty"`+ IngressSocket string `protobuf:"bytes,2,opt,name=ingress_socket,json=ingressSocket,proto3" json:"ingress_socket,omitempty"`+ Error string `protobuf:"bytes,3,opt,name=error,proto3" json:"error,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentAttachResponse) Reset() {+ *x = AgentAttachResponse{}+ mi := &file_api_sam_proto_msgTypes[32]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentAttachResponse) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentAttachResponse) ProtoMessage() {}++func (x *AgentAttachResponse) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[32]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentAttachResponse.ProtoReflect.Descriptor instead.+func (*AgentAttachResponse) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{32}+}++func (x *AgentAttachResponse) GetEgressSocket() string {+ if x != nil {+ return x.EgressSocket+ }+ return ""+}++func (x *AgentAttachResponse) GetIngressSocket() string {+ if x != nil {+ return x.IngressSocket+ }+ return ""+}++func (x *AgentAttachResponse) GetError() string {+ if x != nil {+ return x.Error+ }+ return ""+}++// AgentDetachRequest stops an agent: ingress is unregistered, channels are+// closed and credentials dropped. It must leave no residual advertisement.+type AgentDetachRequest struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ AgentId string `protobuf:"bytes,1,opt,name=agent_id,json=agentId,proto3" json:"agent_id,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentDetachRequest) Reset() {+ *x = AgentDetachRequest{}+ mi := &file_api_sam_proto_msgTypes[33]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentDetachRequest) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentDetachRequest) ProtoMessage() {}++func (x *AgentDetachRequest) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[33]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentDetachRequest.ProtoReflect.Descriptor instead.+func (*AgentDetachRequest) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{33}+}++func (x *AgentDetachRequest) GetAgentId() string {+ if x != nil {+ return x.AgentId+ }+ return ""+}++type AgentDetachResponse struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`+ Error string `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentDetachResponse) Reset() {+ *x = AgentDetachResponse{}+ mi := &file_api_sam_proto_msgTypes[34]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentDetachResponse) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentDetachResponse) ProtoMessage() {}++func (x *AgentDetachResponse) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[34]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentDetachResponse.ProtoReflect.Descriptor instead.+func (*AgentDetachResponse) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{34}+}++func (x *AgentDetachResponse) GetSuccess() bool {+ if x != nil {+ return x.Success+ }+ return false+}++func (x *AgentDetachResponse) GetError() string {+ if x != nil {+ return x.Error+ }+ return ""+}++// AgentRefreshRequest hands in a rotated workload credential. Platforms rotate+// these on their own schedule, which is what bounds how long a stale admission+// stays usable.+type AgentRefreshRequest struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ AgentId string `protobuf:"bytes,1,opt,name=agent_id,json=agentId,proto3" json:"agent_id,omitempty"`+ CredentialPath string `protobuf:"bytes,2,opt,name=credential_path,json=credentialPath,proto3" json:"credential_path,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentRefreshRequest) Reset() {+ *x = AgentRefreshRequest{}+ mi := &file_api_sam_proto_msgTypes[35]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentRefreshRequest) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentRefreshRequest) ProtoMessage() {}++func (x *AgentRefreshRequest) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[35]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentRefreshRequest.ProtoReflect.Descriptor instead.+func (*AgentRefreshRequest) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{35}+}++func (x *AgentRefreshRequest) GetAgentId() string {+ if x != nil {+ return x.AgentId+ }+ return ""+}++func (x *AgentRefreshRequest) GetCredentialPath() string {+ if x != nil {+ return x.CredentialPath+ }+ return ""+}++type AgentRefreshResponse struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`+ Error string `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"`+ ExpiresAt int64 `protobuf:"varint,3,opt,name=expires_at,json=expiresAt,proto3" json:"expires_at,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentRefreshResponse) Reset() {+ *x = AgentRefreshResponse{}+ mi := &file_api_sam_proto_msgTypes[36]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentRefreshResponse) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentRefreshResponse) ProtoMessage() {}++func (x *AgentRefreshResponse) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[36]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentRefreshResponse.ProtoReflect.Descriptor instead.+func (*AgentRefreshResponse) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{36}+}++func (x *AgentRefreshResponse) GetSuccess() bool {+ if x != nil {+ return x.Success+ }+ return false+}++func (x *AgentRefreshResponse) GetError() string {+ if x != nil {+ return x.Error+ }+ return ""+}++func (x *AgentRefreshResponse) GetExpiresAt() int64 {+ if x != nil {+ return x.ExpiresAt+ }+ return 0+}++// AgentStatusRequest reports on one agent, or on all of them when agent_id is+// empty, for a scheduler's reconcile loop.+type AgentStatusRequest struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ AgentId string `protobuf:"bytes,1,opt,name=agent_id,json=agentId,proto3" json:"agent_id,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentStatusRequest) Reset() {+ *x = AgentStatusRequest{}+ mi := &file_api_sam_proto_msgTypes[37]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentStatusRequest) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentStatusRequest) ProtoMessage() {}++func (x *AgentStatusRequest) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[37]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentStatusRequest.ProtoReflect.Descriptor instead.+func (*AgentStatusRequest) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{37}+}++func (x *AgentStatusRequest) GetAgentId() string {+ if x != nil {+ return x.AgentId+ }+ return ""+}++type AgentStatus struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ AgentId string `protobuf:"bytes,1,opt,name=agent_id,json=agentId,proto3" json:"agent_id,omitempty"`+ Attached bool `protobuf:"varint,2,opt,name=attached,proto3" json:"attached,omitempty"`+ Ingress []*AgentIngress `protobuf:"bytes,3,rep,name=ingress,proto3" json:"ingress,omitempty"`+ CredentialExpiresAt int64 `protobuf:"varint,4,opt,name=credential_expires_at,json=credentialExpiresAt,proto3" json:"credential_expires_at,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentStatus) Reset() {+ *x = AgentStatus{}+ mi := &file_api_sam_proto_msgTypes[38]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentStatus) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentStatus) ProtoMessage() {}++func (x *AgentStatus) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[38]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentStatus.ProtoReflect.Descriptor instead.+func (*AgentStatus) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{38}+}++func (x *AgentStatus) GetAgentId() string {+ if x != nil {+ return x.AgentId+ }+ return ""+}++func (x *AgentStatus) GetAttached() bool {+ if x != nil {+ return x.Attached+ }+ return false+}++func (x *AgentStatus) GetIngress() []*AgentIngress {+ if x != nil {+ return x.Ingress+ }+ return nil+}++func (x *AgentStatus) GetCredentialExpiresAt() int64 {+ if x != nil {+ return x.CredentialExpiresAt+ }+ return 0+}++type AgentStatusResponse struct {+ state protoimpl.MessageState `protogen:"open.v1"`+ Agents []*AgentStatus `protobuf:"bytes,1,rep,name=agents,proto3" json:"agents,omitempty"`+ Error string `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"`+ unknownFields protoimpl.UnknownFields+ sizeCache protoimpl.SizeCache+}++func (x *AgentStatusResponse) Reset() {+ *x = AgentStatusResponse{}+ mi := &file_api_sam_proto_msgTypes[39]+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ ms.StoreMessageInfo(mi)+}++func (x *AgentStatusResponse) String() string {+ return protoimpl.X.MessageStringOf(x)+}++func (*AgentStatusResponse) ProtoMessage() {}++func (x *AgentStatusResponse) ProtoReflect() protoreflect.Message {+ mi := &file_api_sam_proto_msgTypes[39]+ if x != nil {+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))+ if ms.LoadMessageInfo() == nil {+ ms.StoreMessageInfo(mi)+ }+ return ms+ }+ return mi.MessageOf(x)+}++// Deprecated: Use AgentStatusResponse.ProtoReflect.Descriptor instead.+func (*AgentStatusResponse) Descriptor() ([]byte, []int) {+ return file_api_sam_proto_rawDescGZIP(), []int{39}+}++func (x *AgentStatusResponse) GetAgents() []*AgentStatus {+ if x != nil {+ return x.Agents+ }+ return nil+}++func (x *AgentStatusResponse) GetError() string {+ if x != nil {+ return x.Error+ }+ return ""+}+var File_api_sam_proto protoreflect.FileDescriptorconst file_api_sam_proto_rawDesc = "" +@@ -2037,6 +2817,58 @@ const file_api_sam_proto_rawDesc = "" +"\apeer_id\x18\x01 \x01(\tR\x06peerId\"E\n" +"\x13TokenRevokeResponse\x12\x18\n" +"\asuccess\x18\x01 \x01(\bR\asuccess\x12\x14\n" ++ "\x05error\x18\x02 \x01(\tR\x05error\"u\n" ++ "\vAgentSecret\x12\x12\n" ++ "\x04host\x18\x01 \x01(\tR\x04host\x12\x12\n" ++ "\x04kind\x18\x02 \x01(\tR\x04kind\x12\x1f\n" ++ "\vheader_name\x18\x03 \x01(\tR\n" ++ "headerName\x12\x1d\n" ++ "\n" ++ "value_path\x18\x04 \x01(\tR\tvaluePath\"R\n" ++ "\vAgentEgress\x12\x14\n" ++ "\x05allow\x18\x01 \x03(\tR\x05allow\x12-\n" ++ "\asecrets\x18\x02 \x03(\v2\x13.sam.v1.AgentSecretR\asecrets\"\x81\x01\n" ++ "\fAgentIngress\x12'\n" ++ "\x04type\x18\x01 \x01(\x0e2\x13.sam.v1.ServiceTypeR\x04type\x12\x12\n" ++ "\x04name\x18\x02 \x01(\tR\x04name\x12\x12\n" ++ "\x04port\x18\x03 \x01(\rR\x04port\x12 \n" ++ "\vdescription\x18\x04 \x01(\tR\vdescription\"\xe9\x01\n" ++ "\vAgentBundle\x12\x18\n" ++ "\aversion\x18\x01 \x01(\tR\aversion\x12\x19\n" ++ "\bagent_id\x18\x02 \x01(\tR\aagentId\x12\x1f\n" ++ "\vexternal_id\x18\x03 \x01(\tR\n" ++ "externalId\x12'\n" ++ "\x0fcredential_path\x18\x04 \x01(\tR\x0ecredentialPath\x12+\n" ++ "\x06egress\x18\x05 \x01(\v2\x13.sam.v1.AgentEgressR\x06egress\x12.\n" ++ "\aingress\x18\x06 \x03(\v2\x14.sam.v1.AgentIngressR\aingress\"A\n" ++ "\x12AgentAttachRequest\x12+\n" ++ "\x06bundle\x18\x01 \x01(\v2\x13.sam.v1.AgentBundleR\x06bundle\"w\n" ++ "\x13AgentAttachResponse\x12#\n" ++ "\regress_socket\x18\x01 \x01(\tR\fegressSocket\x12%\n" ++ "\x0eingress_socket\x18\x02 \x01(\tR\ringressSocket\x12\x14\n" ++ "\x05error\x18\x03 \x01(\tR\x05error\"/\n" ++ "\x12AgentDetachRequest\x12\x19\n" ++ "\bagent_id\x18\x01 \x01(\tR\aagentId\"E\n" ++ "\x13AgentDetachResponse\x12\x18\n" ++ "\asuccess\x18\x01 \x01(\bR\asuccess\x12\x14\n" ++ "\x05error\x18\x02 \x01(\tR\x05error\"Y\n" ++ "\x13AgentRefreshRequest\x12\x19\n" ++ "\bagent_id\x18\x01 \x01(\tR\aagentId\x12'\n" ++ "\x0fcredential_path\x18\x02 \x01(\tR\x0ecredentialPath\"e\n" ++ "\x14AgentRefreshResponse\x12\x18\n" ++ "\asuccess\x18\x01 \x01(\bR\asuccess\x12\x14\n" ++ "\x05error\x18\x02 \x01(\tR\x05error\x12\x1d\n" ++ "\n" ++ "expires_at\x18\x03 \x01(\x03R\texpiresAt\"/\n" ++ "\x12AgentStatusRequest\x12\x19\n" ++ "\bagent_id\x18\x01 \x01(\tR\aagentId\"\xa8\x01\n" ++ "\vAgentStatus\x12\x19\n" ++ "\bagent_id\x18\x01 \x01(\tR\aagentId\x12\x1a\n" ++ "\battached\x18\x02 \x01(\bR\battached\x12.\n" ++ "\aingress\x18\x03 \x03(\v2\x14.sam.v1.AgentIngressR\aingress\x122\n" ++ "\x15credential_expires_at\x18\x04 \x01(\x03R\x13credentialExpiresAt\"X\n" ++ "\x13AgentStatusResponse\x12+\n" ++ "\x06agents\x18\x01 \x03(\v2\x13.sam.v1.AgentStatusR\x06agents\x12\x14\n" +"\x05error\x18\x02 \x01(\tR\x05error*\x94\x01\n" +"\x10EnrollmentStatus\x12!\n" +"\x1dENROLLMENT_STATUS_UNSPECIFIED\x10\x00\x12\x1d\n" +@@ -2061,7 +2893,7 @@ func file_api_sam_proto_rawDescGZIP() []byte {}var file_api_sam_proto_enumTypes = make([]protoimpl.EnumInfo, 3)-var file_api_sam_proto_msgTypes = make([]protoimpl.MessageInfo, 31)+var file_api_sam_proto_msgTypes = make([]protoimpl.MessageInfo, 44)var file_api_sam_proto_goTypes = []any{(EnrollmentStatus)(0), // 0: sam.v1.EnrollmentStatus(ServiceType)(0), // 1: sam.v1.ServiceType@@ -2093,31 +2925,51 @@ var file_api_sam_proto_goTypes = []any{(*TokenRefreshResponse)(nil), // 27: sam.v1.TokenRefreshResponse(*TokenRevokeRequest)(nil), // 28: sam.v1.TokenRevokeRequest(*TokenRevokeResponse)(nil), // 29: sam.v1.TokenRevokeResponse- nil, // 30: sam.v1.EnrollRequest.LabelsEntry- nil, // 31: sam.v1.BootstrapEnrollRequest.LabelsEntry- nil, // 32: sam.v1.CommandBackend.EnvEntry- nil, // 33: sam.v1.ServiceAnnounce.LabelsEntry+ (*AgentSecret)(nil), // 30: sam.v1.AgentSecret+ (*AgentEgress)(nil), // 31: sam.v1.AgentEgress+ (*AgentIngress)(nil), // 32: sam.v1.AgentIngress+ (*AgentBundle)(nil), // 33: sam.v1.AgentBundle+ (*AgentAttachRequest)(nil), // 34: sam.v1.AgentAttachRequest+ (*AgentAttachResponse)(nil), // 35: sam.v1.AgentAttachResponse+ (*AgentDetachRequest)(nil), // 36: sam.v1.AgentDetachRequest+ (*AgentDetachResponse)(nil), // 37: sam.v1.AgentDetachResponse+ (*AgentRefreshRequest)(nil), // 38: sam.v1.AgentRefreshRequest+ (*AgentRefreshResponse)(nil), // 39: sam.v1.AgentRefreshResponse+ (*AgentStatusRequest)(nil), // 40: sam.v1.AgentStatusRequest+ (*AgentStatus)(nil), // 41: sam.v1.AgentStatus+ (*AgentStatusResponse)(nil), // 42: sam.v1.AgentStatusResponse+ nil, // 43: sam.v1.EnrollRequest.LabelsEntry+ nil, // 44: sam.v1.BootstrapEnrollRequest.LabelsEntry+ nil, // 45: sam.v1.CommandBackend.EnvEntry+ nil, // 46: sam.v1.ServiceAnnounce.LabelsEntry}var file_api_sam_proto_depIdxs = []int32{2, // 0: sam.v1.MeshEvent.type:type_name -> sam.v1.MeshEvent.Type- 30, // 1: sam.v1.EnrollRequest.labels:type_name -> sam.v1.EnrollRequest.LabelsEntry- 31, // 2: sam.v1.BootstrapEnrollRequest.labels:type_name -> sam.v1.BootstrapEnrollRequest.LabelsEntry+ 43, // 1: sam.v1.EnrollRequest.labels:type_name -> sam.v1.EnrollRequest.LabelsEntry+ 44, // 2: sam.v1.BootstrapEnrollRequest.labels:type_name -> sam.v1.BootstrapEnrollRequest.LabelsEntry0, // 3: sam.v1.BootstrapEnrollResponse.status:type_name -> sam.v1.EnrollmentStatus1, // 4: sam.v1.ServiceInfo.type:type_name -> sam.v1.ServiceType- 32, // 5: sam.v1.CommandBackend.env:type_name -> sam.v1.CommandBackend.EnvEntry+ 45, // 5: sam.v1.CommandBackend.env:type_name -> sam.v1.CommandBackend.EnvEntry11, // 6: sam.v1.RegisterServiceRequest.service:type_name -> sam.v1.ServiceInfo12, // 7: sam.v1.RegisterServiceRequest.command:type_name -> sam.v1.CommandBackend1, // 8: sam.v1.ServiceAnnounce.type:type_name -> sam.v1.ServiceType- 33, // 9: sam.v1.ServiceAnnounce.labels:type_name -> sam.v1.ServiceAnnounce.LabelsEntry+ 46, // 9: sam.v1.ServiceAnnounce.labels:type_name -> sam.v1.ServiceAnnounce.LabelsEntry19, // 10: sam.v1.PolicyConfigGetResponse.roles:type_name -> sam.v1.PolicyRole20, // 11: sam.v1.PolicyConfigGetResponse.bindings:type_name -> sam.v1.PolicyBinding19, // 12: sam.v1.PolicyConfigUpdateRequest.roles:type_name -> sam.v1.PolicyRole20, // 13: sam.v1.PolicyConfigUpdateRequest.bindings:type_name -> sam.v1.PolicyBinding- 14, // [14:14] is the sub-list for method output_type- 14, // [14:14] is the sub-list for method input_type- 14, // [14:14] is the sub-list for extension type_name- 14, // [14:14] is the sub-list for extension extendee- 0, // [0:14] is the sub-list for field type_name+ 30, // 14: sam.v1.AgentEgress.secrets:type_name -> sam.v1.AgentSecret+ 1, // 15: sam.v1.AgentIngress.type:type_name -> sam.v1.ServiceType+ 31, // 16: sam.v1.AgentBundle.egress:type_name -> sam.v1.AgentEgress+ 32, // 17: sam.v1.AgentBundle.ingress:type_name -> sam.v1.AgentIngress+ 33, // 18: sam.v1.AgentAttachRequest.bundle:type_name -> sam.v1.AgentBundle+ 32, // 19: sam.v1.AgentStatus.ingress:type_name -> sam.v1.AgentIngress+ 41, // 20: sam.v1.AgentStatusResponse.agents:type_name -> sam.v1.AgentStatus+ 21, // [21:21] is the sub-list for method output_type+ 21, // [21:21] is the sub-list for method input_type+ 21, // [21:21] is the sub-list for extension type_name+ 21, // [21:21] is the sub-list for extension extendee+ 0, // [0:21] is the sub-list for field type_name}func init() { file_api_sam_proto_init() }@@ -2135,7 +2987,7 @@ func file_api_sam_proto_init() {GoPackagePath: reflect.TypeOf(x{}).PkgPath(),RawDescriptor: unsafe.Slice(unsafe.StringData(file_api_sam_proto_rawDesc), len(file_api_sam_proto_rawDesc)),NumEnums: 3,- NumMessages: 31,+ NumMessages: 44,NumExtensions: 0,NumServices: 0,},diff --git a/api/sam.proto b/api/sam.protoindex 371e2ea1..c879f327 100644--- a/api/sam.proto+++ b/api/sam.proto@@ -224,4 +224,124 @@ message TokenRevokeResponse {}+// ============================================================================+// Agent Sandbox Connector API+// ============================================================================+//+// The interface an agent scheduler (Agent Substrate, or any other) implements+// to place agents on the mesh. It is host-local and served on a control socket+// that is deliberately not reachable from inside a sandbox: identity must never+// arrive in band from the agent itself, which could only lie about it.++// AgentSecret configures credential injection for one destination. It carries+// a path, never a value: secret material must not travel through this API.+message AgentSecret {+ string host = 1;+ string kind = 2; // bearer | basicauth | customheader+ string header_name = 3; // customheader only+ string value_path = 4;+}++// AgentEgress is deny-by-default. Patterns are matched against the destination+// name taken from the sandbox boundary, never against a resolved address.+message AgentEgress {+ repeated string allow = 1;+ repeated AgentSecret secrets = 2;+}++// AgentIngress declares that the agent serves a mesh service. The name is the+// service half of the mesh host the rest of the mesh dials (see api/names.go);+// port is where the agent listens inside its sandbox.+message AgentIngress {+ ServiceType type = 1;+ string name = 2;+ uint32 port = 3;+ string description = 4;+}++// AgentBundle is everything the platform declares about one agent. Its+// canonical form is a YAML file in the agent's own state directory, so that a+// suspend/resume onto another host carries it with no extra machinery; this+// message is the transport mirror of that file.+message AgentBundle {+ string version = 1;++ // Canonical mesh identifier, without the "agent:" prefix. Dot-separated and+ // DNS-shaped; see api/agent.go for the rules and why they exist.+ string agent_id = 2;++ // The platform's own identifier, verbatim, kept for audit because the+ // translation into agent_id is not always reversible.+ string external_id = 3;++ // Path to the workload credential the platform already issues: a projected+ // Kubernetes service-account token, a pod certificate, or an SVID. It is+ // verified at admission against the platform's issuer and then translated+ // into agent facts, the same way OIDC claims are translated at node+ // enrollment. The scheduler needs no mesh credential of its own.+ string credential_path = 4;++ AgentEgress egress = 5;+ repeated AgentIngress ingress = 6;+}++// AgentAttachRequest admits an agent. It is idempotent on agent_id: resuming+// after a crash or a migration is another Attach, not a distinct operation.+message AgentAttachRequest {+ AgentBundle bundle = 1;+}++message AgentAttachResponse {+ // Sandbox boundary endpoints to wire into the sandbox: SOCKS5 for guest to+ // host, and a reverse channel for host to guest that is empty when the+ // bundle declares no ingress.+ string egress_socket = 1;+ string ingress_socket = 2;+ string error = 3;+}++// AgentDetachRequest stops an agent: ingress is unregistered, channels are+// closed and credentials dropped. It must leave no residual advertisement.+message AgentDetachRequest {+ string agent_id = 1;+}++message AgentDetachResponse {+ bool success = 1;+ string error = 2;+}++// AgentRefreshRequest hands in a rotated workload credential. Platforms rotate+// these on their own schedule, which is what bounds how long a stale admission+// stays usable.+message AgentRefreshRequest {+ string agent_id = 1;+ string credential_path = 2;+}++message AgentRefreshResponse {+ bool success = 1;+ string error = 2;+ int64 expires_at = 3;+}++// AgentStatusRequest reports on one agent, or on all of them when agent_id is+// empty, for a scheduler's reconcile loop.+message AgentStatusRequest {+ string agent_id = 1;+}++message AgentStatus {+ string agent_id = 1;+ bool attached = 2;+ repeated AgentIngress ingress = 3;+ int64 credential_expires_at = 4;+}++message AgentStatusResponse {+ repeated AgentStatus agents = 1;+ string error = 2;+}++diff --git a/site/content/docs/agent-architecture.md b/site/content/docs/agent-architecture.mdindex b9b39698..7e7399f5 100644--- a/site/content/docs/agent-architecture.md+++ b/site/content/docs/agent-architecture.md@@ -774,11 +774,13 @@ Two things to settle **with** the Substrate side rather than assume:### 12.5 Still to settle-* **Wire format** for `Attach`/`Detach`/`Refresh`/`Status`: proto in- `api/sam.proto` (AGENTS.md's rule) versus a YAML bundle plus a small local- HTTP endpoint. Substrate is Go, so proto costs its connector nothing;- Python/TypeScript connectors would prefer HTTP. Leaning proto for the- operations, YAML for the bundle.+* **Wire format — decided.** Proto in `api/sam.proto` for the operations+ (`AgentAttach`/`AgentDetach`/`AgentRefresh`/`AgentStatus` request and response+ messages), YAML for the bundle. Substrate is Go, so proto costs its connector+ nothing; the bundle stays YAML because its canonical copy is a file in the+ agent's state directory, where it has to be readable and diffable by whoever+ operates the platform. `AgentBundle` in the proto is the transport mirror of+ that file, not a second source of truth.* **Bulk pre-creation is deliberately not in v1** — premature until the semanticsare proven. What v1 owes it is *room*: `Attach` takes a bundle and isidempotent per agent id, so `AttachBatch` is a purely additive operation