capability.proto

Every Selu capability exposes a gRPC server that implements the Capability service defined below. The orchestrator calls Invoke (or StreamInvoke) when an agent uses a capability tool, Healthcheck to monitor liveness, and the artifact RPCs to pass files in and out.

Service definition

capability.proto

syntax = "proto3";
package selu.capability;

service Capability {
  rpc Invoke(InvokeRequest) returns (InvokeResponse);
  rpc StreamInvoke(InvokeRequest) returns (stream InvokeChunk);
  rpc Healthcheck(HealthRequest) returns (HealthResponse);
  rpc UploadInputArtifact(stream UploadInputArtifactChunk) returns (UploadInputArtifactResponse);
  rpc DownloadOutputArtifact(DownloadOutputArtifactRequest) returns (stream ArtifactChunk);
}

message InvokeRequest {
  string tool_name = 1;
  bytes args_json = 2;
  bytes config_json = 3;
  string session_id = 4;
  string capability_id = 5;
  string thread_id = 6;
}

message InvokeResponse {
  bytes result_json = 1;
  string error = 2;
}

message InvokeChunk {
  bytes data = 1;
  bool done = 2;
  string error = 3;
}

message HealthRequest {}

message HealthResponse {
  bool ready = 1;
  string message = 2;
}

message UploadInputArtifactChunk {
  bytes data = 1;
  string filename = 2;
  string mime_type = 3;
}

message UploadInputArtifactResponse {
  string capability_artifact_id = 1;
  string error = 2;
}

message DownloadOutputArtifactRequest {
  string artifact_id = 1;
}

message ArtifactChunk {
  bytes data = 1;
  string filename = 2;
  string mime_type = 3;
  bool done = 4;
  string error = 5;
}

RPCs

RPC	Request	Response	Description
Invoke	InvokeRequest	InvokeResponse	Execute a tool and return the full result in one response.
StreamInvoke	InvokeRequest	stream InvokeChunk	Execute a tool and stream partial results back as chunks.
Healthcheck	HealthRequest	HealthResponse	Report whether the capability is ready to accept requests.
UploadInputArtifact	stream UploadInputArtifactChunk	UploadInputArtifactResponse	Stream a file into the capability before invocation.
DownloadOutputArtifact	DownloadOutputArtifactRequest	stream ArtifactChunk	Stream a file out of the capability after invocation.

Messages

InvokeRequest

Sent by the orchestrator when an agent calls a tool on this capability.

Field	Number	Type	Description
tool_name	1	string	The name of the tool to execute (must match a tool declared in manifest.yaml or returned by dynamic discovery).
args_json	2	bytes	JSON-encoded tool arguments conforming to the tool’s input_schema.
config_json	3	bytes	JSON-encoded configuration object. Contains credentials and any other runtime config injected by the orchestrator.
session_id	4	string	Identifier for the current user session.
capability_id	5	string	The unique identifier of this capability instance.
thread_id	6	string	Identifier for the conversation thread that triggered this invocation.

Tip

config_json is where the orchestrator delivers credentials. If your manifest.yaml declares a credential named GITHUB_TOKEN, it will appear as a key inside the parsed config_json object. There is no separate credentials field — everything arrives in config_json.

InvokeResponse

Returned by Invoke with the full result.

Field	Number	Type	Description
result_json	1	bytes	JSON-encoded result data.
error	2	string	If non-empty, the invocation failed and this contains the error message.

InvokeChunk

Streamed back by StreamInvoke as partial results become available.

Field	Number	Type	Description
data	1	bytes	A chunk of the result payload.
done	2	bool	true on the final chunk in the stream.
error	3	string	If non-empty, the stream is terminating with an error.

HealthRequest

Empty message. No fields.

HealthResponse

Field	Number	Type	Description
ready	1	bool	true when the capability is ready to accept invocations.
message	2	string	Optional human-readable status detail (e.g. reason for not being ready).

UploadInputArtifactChunk

Streamed to the capability by the orchestrator to deliver an input file.

Field	Number	Type	Description
data	1	bytes	A chunk of the file contents.
filename	2	string	Original filename. Set on the first chunk; may be empty on subsequent chunks.
mime_type	3	string	MIME type of the file. Set on the first chunk; may be empty on subsequent chunks.

UploadInputArtifactResponse

Field	Number	Type	Description
capability_artifact_id	1	string	An identifier the capability assigns to the uploaded artifact, used to reference it during invocation.
error	2	string	If non-empty, the upload failed.

DownloadOutputArtifactRequest

Field	Number	Type	Description
artifact_id	1	string	The identifier of the artifact to download.

ArtifactChunk

Streamed back to the orchestrator when downloading an output artifact.

Field	Number	Type	Description
data	1	bytes	A chunk of the file contents.
filename	2	string	Original filename. Set on the first chunk.
mime_type	3	string	MIME type of the file. Set on the first chunk.
done	4	bool	true on the final chunk in the stream.
error	5	string	If non-empty, the download is terminating with an error.

Key design decisions

bytes vs string for JSON fields

args_json, config_json, and result_json are typed as bytes rather than string. This avoids double-encoding issues when the JSON payload contains arbitrary binary data or non-UTF-8 sequences. In most languages the practical difference is minimal — you serialize your JSON to a byte array and assign it directly.

Credentials in config_json

There is no dedicated credentials field. The orchestrator bundles credentials declared in manifest.yaml into the config_json object alongside any other runtime configuration. This keeps the proto surface small and lets the orchestrator add new config keys without a proto change.

Caution

The args_json field must be valid JSON that conforms to the input_schema declared for the tool in your manifest.yaml. The orchestrator validates the payload before forwarding it. Malformed JSON will result in an INVALID_ARGUMENT gRPC status.

Streaming with InvokeChunk

StreamInvoke returns a dedicated InvokeChunk message instead of reusing InvokeResponse. Each chunk carries a data payload and a done flag so the client knows when the stream is complete. This is useful for capabilities that produce incremental output such as search results or progress updates.

Artifacts for file transfer

Artifacts are the mechanism for passing files between the orchestrator and capabilities. Before invoking a tool that needs a file, the orchestrator streams the file in via UploadInputArtifact and receives a capability_artifact_id that can be referenced in args_json. After invocation, the orchestrator can retrieve output files via DownloadOutputArtifact. Both directions use chunked streaming so there is no hard size limit on files.

Generating client/server code

Use buf or protoc to generate stubs in your language of choice:

# Using buf (recommended)
buf generate proto/capability.proto

# Using protoc directly (Go example)
protoc --go_out=. --go-grpc_out=. proto/capability.proto

# Python example
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. proto/capability.proto

The official Selu SDKs for Go and Python include pre-generated stubs, so you typically do not need to run code generation yourself.

Health checks

The orchestrator calls Healthcheck periodically. If a capability returns ready: false or fails to respond within the timeout, the orchestrator marks it as unhealthy and stops routing invocations until it recovers.