Documentation
¶
Overview ¶
Package collab contains the deliberately small collaboration boundary used by the injected MessageAgent MCP process. The package owns the broker wire DTOs and framing, but it does not import Harness or ACP types.
Index ¶
- Constants
- Variables
- func DecodeCapabilityToken(encoded string) ([]byte, error)
- func EncodeCapabilityToken(capability []byte) (string, error)
- func ReadFrame(r io.Reader) ([]byte, error)
- func ReadHandshake(r io.Reader) ([]byte, error)
- func WriteFrame(w io.Writer, payload []byte) error
- func WriteFrameLimit(w io.Writer, payload []byte, max int) error
- func WriteHandshake(w io.Writer, capability []byte) error
- type Client
- func (c *Client) Call(ctx context.Context, request MessageAgentRequest) (DelegateResult, error)
- func (c *Client) CallJSON(ctx context.Context, request MessageAgentRequest) (json.RawMessage, error)
- func (c *Client) CallRaw(ctx context.Context, request MessageAgentRequest) (json.RawMessage, error)
- func (c *Client) Config() ClientConfig
- func (c *Client) MessageAgent(ctx context.Context, request MessageAgentRequest) (DelegateResult, error)
- func (c *Client) Send(ctx context.Context, request MessageAgentRequest) (DelegateResult, error)
- type ClientConfig
- type Config
- type DelegateResult
- type DialFunc
- type MessageAgentRequest
- type PreparedMessageAgent
Constants ¶
const ( // EndpointEnv and TokenEnv are the only environment entries accepted by // carbon-collab-mcp. They are intentionally constants rather than flags so // a token can never arrive through process arguments. EndpointEnv = "CODERIG_COLLAB_ENDPOINT" TokenEnv = "CODERIG_COLLAB_TOKEN" // #nosec G101 -- environment variable name, not a credential // Aliases make the environment contract explicit at call sites without // creating alternate accepted names. EndpointEnvName = EndpointEnv TokenEnvName = TokenEnv BrokerEndpointEnv = EndpointEnv BrokerTokenEnv = TokenEnv ToolName = "MessageAgent" CapabilityBytes = 32 MaxCapabilityBytes = CapabilityBytes // MaxMessageBytes is the existing MessageAgent message bound. MaxMessageBytes = 192 << 10 // MaxArgumentBytes bounds the encoded tools/call argument object. MaxArgumentBytes = 256 << 10 // MaxFrameBytes bounds one broker length-prefixed JSON frame. It is large // enough for a maximum argument/result plus the small DTO envelope. MaxFrameBytes = MaxArgumentBytes // MaxEndpointBytes prevents an unbounded path from entering a dial call. MaxEndpointBytes = 4096 MaxTimeoutSeconds = 24 * 60 * 60 )
Variables ¶
var ( ErrInvalidRequest = errors.New("invalid collaboration request") ErrInvalidArguments = ErrInvalidRequest ErrInputLimit = errors.New("collaboration input exceeds limit") ErrInvalidCapability = errors.New("invalid collaboration capability") ErrInvalidConfig = errors.New("invalid collaboration configuration") ErrFrameLimit = errors.New("collaboration frame exceeds limit") ErrFrameTooLarge = ErrFrameLimit ErrFrame = errors.New("invalid collaboration frame") ErrAuthentication = errors.New("collaboration authentication failed") ErrAuth = ErrAuthentication ErrConnection = errors.New("collaboration connection failed") ErrAdmission = errors.New("collaboration admission failed") ErrResponse = errors.New("collaboration response failed") ErrDeadline = errors.New("collaboration deadline exceeded") ErrUnsupportedPlatform = errors.New("collaboration IPC unsupported on this platform") )
Functions ¶
func DecodeCapabilityToken ¶
DecodeCapabilityToken decodes the fixed hexadecimal environment format.
func EncodeCapabilityToken ¶
EncodeCapabilityToken returns the lowercase hexadecimal environment format.
func ReadHandshake ¶
ReadHandshake reads and validates one length-prefixed raw capability.
func WriteFrame ¶
WriteFrame writes one length-prefixed broker payload.
func WriteFrameLimit ¶
WriteFrameLimit is the configurable-bound counterpart to WriteFrame. It is exported so the Harness broker can use the same framing without importing a transport implementation.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client performs one authenticated request per broker connection. It is safe for concurrent use because no mutable connection is shared between calls.
func NewClient ¶
func NewClient(cfg ClientConfig) (*Client, error)
NewClient validates configuration and creates a Unix-domain broker client.
func NewClientWithDialer ¶
func NewClientWithDialer(cfg ClientConfig, dial DialFunc) (*Client, error)
NewClientWithDialer creates a client with an injected local dialer. The endpoint and capability are still validated exactly as in NewClient.
func (*Client) Call ¶
func (c *Client) Call(ctx context.Context, request MessageAgentRequest) (DelegateResult, error)
Call sends one MessageAgent request and decodes its public result. Request validation completes before dialing the broker.
func (*Client) CallJSON ¶
func (c *Client) CallJSON(ctx context.Context, request MessageAgentRequest) (json.RawMessage, error)
CallJSON returns the bounded, validated public result JSON without exposing broker-internal request or capability data. Keeping the original bytes also preserves the distinction between an omitted and an explicitly empty response field in the public envelope.
func (*Client) CallRaw ¶
func (c *Client) CallRaw(ctx context.Context, request MessageAgentRequest) (json.RawMessage, error)
CallRaw is an explicit raw-JSON alias for CallJSON.
func (*Client) Config ¶
func (c *Client) Config() ClientConfig
Config returns a defensive copy of the immutable client policy.
func (*Client) MessageAgent ¶
func (c *Client) MessageAgent(ctx context.Context, request MessageAgentRequest) (DelegateResult, error)
MessageAgent is an explicit operation-named alias for Call.
func (*Client) Send ¶
func (c *Client) Send(ctx context.Context, request MessageAgentRequest) (DelegateResult, error)
Send is a concise operation-named alias for Call.
type ClientConfig ¶
type ClientConfig struct {
Endpoint string
Capability []byte
Token []byte
ConnectTimeout time.Duration
AdmissionTimeout time.Duration
MaxFrameBytes int
}
ClientConfig configures one authenticated broker call. Capability is a raw 32-byte value; the process environment uses its lowercase hexadecimal representation. Token is retained as a descriptive input alias for callers that use token terminology; supplying both fields is rejected unless they are byte-for-byte identical.
func ConfigFromEnv ¶
func ConfigFromEnv(lookup func(string) (string, bool)) (ClientConfig, error)
ConfigFromEnv reads the fixed endpoint and token environment entries. The supplied lookup function keeps startup unit-testable without mutating the process environment.
type DelegateResult ¶
type DelegateResult struct {
AgentID string `json:"agent_id"`
Name string `json:"name"`
State string `json:"state"`
DeliveryStatus string `json:"delivery_status,omitempty"`
ResponseStatus string `json:"response_status,omitempty"`
Response string `json:"response,omitempty"`
}
DelegateResult is the public, correlation-free result envelope returned by the broker. Internal request IDs and controller details are intentionally not represented by this type.
func DecodeDelegateResult ¶
func DecodeDelegateResult(raw []byte) (DelegateResult, error)
DecodeDelegateResult validates a broker result and strips unknown internal fields from the public projection.
type DialFunc ¶
DialFunc is the narrow connection seam used by Client. Production clients use a Unix-domain socket; tests and embedders may provide an equivalent local connection without changing the framing or authentication policy.
type MessageAgentRequest ¶
type MessageAgentRequest struct {
AgentID string `json:"agent_id"`
Message string `json:"message"`
WaitForResponse bool `json:"wait_for_response"`
TimeoutSeconds *int `json:"timeout_seconds,omitempty"`
}
MessageAgentRequest is the complete model-visible MessageAgent argument object. No identity or correlation field belongs here; the broker derives those values from the authenticated capability and runtime context.
func DecodeMessageAgent ¶
func DecodeMessageAgent(raw []byte) (MessageAgentRequest, error)
DecodeMessageAgent strictly validates one MessageAgent argument object. Validation happens before any client dial or frame write.
func ValidateMessageAgent ¶
func ValidateMessageAgent(raw []byte) (MessageAgentRequest, error)
ValidateMessageAgent is an explicit spelling for DecodeMessageAgent.
type PreparedMessageAgent ¶
type PreparedMessageAgent = MessageAgentRequest
PreparedMessageAgent is a descriptive alias for a validated request.
Source Files