Files
codex/codex-rs/code-mode-protocol/src/grpc/codex.code_mode.v1.proto
T
Charlie Marsh fef47a6769 Reuse code-mode tool catalogs across executions (#61846)
## Why

Repeated executions with the same tools resend the full catalog and duplicate tool metadata. Catalog revisions let clients reuse an acknowledged catalog within a session.

## What changed

- Negotiate catalog revision support over stdio and gRPC, retaining full requests for hosts without support.
- Send tool definitions when installing a revision, then reference that revision for matching executions. Commit client catalog state only after execution admission succeeds; concurrent admissions can send full requests.
- Keep immutable tool snapshots for each cell, reject invalid, unknown, or conflicting revisions, and share identical definitions and runtime metadata across sessions in the same process.

## Testing

Add tests for acknowledged reuse, abandoned admissions, changed definitions, revision conflicts, session isolation, snapshot lifetimes, and shared metadata.

GitOrigin-RevId: d2f29bf668bc2279715f5f1b7d24310923c57d33
2026-11-16 17:47:49 +00:00

336 lines
9.3 KiB
Protocol Buffer

syntax = "proto3";
package codex.code_mode.v1;
// Hosts stateful JavaScript execution and delegates nested tool calls to the
// session owner. Large tool inputs and outputs stay off the session event
// stream so independent HTTP/2 streams can make progress concurrently.
//
// Execute (including its stream), Wait, and Terminate reserve NOT_FOUND for an
// unknown session_id. Clients may retire the session binding on this status.
// Missing cells use WaitResponse.missing_cell instead.
service CodeModeHost {
// Optional host-level observation. UNIMPLEMENTED means no collector. Sampling
// never opens/closes a session and failures affect only this RPC stream.
rpc GetProcessMetrics(GetProcessMetricsRequest) returns (GetProcessMetricsResponse);
// Opens a session lease. The first event is always SessionOpened; dropping
// this stream closes the session and terminates its active cells.
rpc OpenSession(OpenSessionRequest) returns (stream SessionEvent);
rpc CloseSession(CloseSessionRequest) returns (CloseSessionResponse);
// Each subscription owns an independent stream of matching invocations. An
// empty tool_names filter matches every tool. Each invocation is routed to
// exactly one matching subscription, even when filters overlap.
rpc SubscribeToToolCalls(SubscribeToToolCallsRequest)
returns (stream ToolCall);
// Each result receives its own HTTP/2 stream, preventing a large response
// from blocking unrelated tool completions or session control events.
// NOT_FOUND may identify a missing invocation rather than a missing session.
rpc CompleteToolCall(CompleteToolCallRequest)
returns (CompleteToolCallResponse);
rpc AcknowledgeNotification(AcknowledgeNotificationRequest)
returns (AcknowledgeNotificationResponse);
// Emits ExecutionStarted immediately, followed by one ExecutionOutcome when
// the execution yields, completes, or is terminated.
rpc Execute(ExecuteRequest) returns (stream ExecuteEvent);
rpc Wait(WaitRequest) returns (WaitResponse);
// Ends the current observation early without stopping its cell. The
// corresponding Execute or Wait still returns its ordinary outcome.
rpc YieldObservation(YieldObservationRequest) returns (YieldObservationResponse);
// Acknowledges that a canceled wait has retired before another wait starts.
rpc CancelWait(CancelWaitRequest) returns (CancelWaitResponse);
rpc Terminate(TerminateRequest) returns (WaitResponse);
}
message GetProcessMetricsRequest {}
message GetProcessMetricsResponse {
uint32 process_id = 1;
double process_start_time_seconds = 2;
double cpu_seconds_total = 3;
uint64 resident_memory_bytes = 4;
}
message OpenSessionRequest {
optional SessionCellExecutionLimits cell_execution_limits = 1;
// Absent preserves the legacy client-side truncation behavior.
optional OutputTruncation output_truncation = 2;
// Maximum pending tool callbacks the client can accept.
// Absent preserves the legacy 1,024 callback budget. Hosts may impose a lower
// shared limit, and older hosts ignore this field and retain their own limit.
optional uint32 max_pending_delegate_calls = 3;
reserved 4; // Boolean heartbeat opt-in used by earlier preview builds.
// Seconds of stream inactivity before a heartbeat. Zero disables heartbeats.
uint32 heartbeat_interval_s = 5;
}
enum OutputTruncation {
OUTPUT_TRUNCATION_UNSPECIFIED = 0;
OUTPUT_TRUNCATION_CLIENT = 1;
OUTPUT_TRUNCATION_SERVER = 2;
}
message SessionCellExecutionLimits {
optional uint64 max_yield_time_ms = 1;
optional uint64 max_heap_size_bytes = 2;
}
message SessionEvent {
oneof event {
SessionOpened opened = 1;
ToolCallCancelled tool_call_cancelled = 2;
Notification notification = 3;
NotificationCancelled notification_cancelled = 4;
CellClosed cell_closed = 5;
StreamHeartbeat heartbeat = 6;
}
}
message SessionOpened {
string session_id = 1;
// Absent (including from an older host) means the client owns truncation.
optional OutputTruncation output_truncation = 2;
// Clients may send ExecuteRequest.catalog_revision when advertised.
bool supports_catalog_revision = 3;
}
message CloseSessionRequest {
string session_id = 1;
}
message CloseSessionResponse {}
message SubscribeToToolCallsRequest {
string session_id = 1;
repeated ToolName tool_names = 2;
reserved 3; // Boolean heartbeat opt-in used by earlier preview builds.
// Seconds of stream inactivity before a heartbeat. Zero disables heartbeats.
uint32 heartbeat_interval_s = 4;
}
message StreamHeartbeat {}
message ToolCall {
string session_id = 1;
// Correlates callbacks with Execute before ExecutionStarted is received.
string execution_id = 2;
string cell_id = 3;
string invocation_id = 4;
string runtime_tool_call_id = 5;
ToolName tool_name = 6;
ToolKind tool_kind = 7;
optional bytes input_json = 8;
// Starts at one and increases independently for each execution.
uint64 sequence = 9;
// The host tool invocation span's W3C parent context for this streamed callback.
// gRPC metadata is fixed when the subscription stream opens, so each call
// carries its own context in the message.
optional string traceparent = 10;
// A heartbeat carries only the session ID and must not be handled as a tool call.
optional StreamHeartbeat heartbeat = 11;
}
message CompleteToolCallRequest {
string session_id = 1;
string invocation_id = 2;
oneof outcome {
ToolCallSucceeded succeeded = 3;
ToolCallFailed failed = 4;
}
}
message ToolCallSucceeded {
bytes output_json = 1;
}
message ToolCallFailed {
string message = 1;
}
message CompleteToolCallResponse {}
message ToolCallCancelled {
string invocation_id = 1;
// Cancellation can arrive before the corresponding ToolCall because session
// control events and tool subscriptions use independent HTTP/2 streams.
}
message Notification {
string notification_id = 1;
string execution_id = 2;
string cell_id = 3;
string call_id = 4;
string text = 5;
}
message NotificationCancelled {
string notification_id = 1;
}
message AcknowledgeNotificationRequest {
string session_id = 1;
string notification_id = 2;
}
message AcknowledgeNotificationResponse {}
message CellClosed {
string execution_id = 1;
string cell_id = 2;
// Last tool-call sequence issued before closure. Clients may retire the cell
// immediately and reject tool calls delivered after its closure.
uint64 final_tool_call_sequence = 3;
}
message ExecuteRequest {
string session_id = 1;
// Chosen by the client so callbacks can be correlated before cell admission.
string execution_id = 2;
string tool_call_id = 3;
string source = 4;
repeated ToolDefinition enabled_tools = 5;
optional uint64 yield_time_ms = 6;
optional uint64 max_output_tokens = 7;
// Nonempty enabled_tools installs a session-local revision. Empty references it.
optional uint64 catalog_revision = 8;
}
message ExecuteEvent {
oneof event {
ExecutionStarted started = 1;
ExecutionOutcome outcome = 2;
}
}
message ExecutionStarted {
string execution_id = 1;
string cell_id = 2;
}
message WaitRequest {
string session_id = 1;
string cell_id = 2;
string wait_id = 3;
uint64 yield_time_ms = 4;
// Only set for a session that selected server-side output truncation.
optional uint64 max_output_tokens = 5;
}
message WaitResponse {
oneof state {
ExecutionOutcome live_cell = 1;
ExecutionOutcome missing_cell = 2;
}
}
message CancelWaitRequest {
string session_id = 1;
string wait_id = 2;
}
message CancelWaitResponse {}
message YieldObservationRequest {
string session_id = 1;
oneof observation {
string execution_id = 2;
string wait_id = 3;
}
}
message YieldObservationResponse {}
message TerminateRequest {
string session_id = 1;
string cell_id = 2;
// The terminating observation has its own output budget.
optional uint64 max_output_tokens = 3;
}
message ExecutionOutcome {
string cell_id = 1;
repeated ContentItem content_items = 2;
// Elapsed monotonic time from receipt of this Execute, Wait, or Terminate
// request until its outcome is ready, before serialization and delivery.
// Includes nested tool waits, but not background time between requests.
// Always supplied by the host; zero is a valid measurement.
uint64 code_mode_host_duration_ns = 6;
oneof outcome {
ExecutionYielded yielded = 3;
ExecutionTerminated terminated = 4;
ExecutionCompleted completed = 5;
}
}
message ExecutionYielded {}
message ExecutionTerminated {}
message ExecutionCompleted {
optional string error_text = 1;
}
message ToolDefinition {
string name = 1;
ToolName tool_name = 2;
string description = 3;
ToolKind kind = 4;
optional bytes input_schema_json = 5;
optional bytes output_schema_json = 6;
}
message ToolName {
string name = 1;
optional string namespace = 2;
}
enum ToolKind {
TOOL_KIND_UNSPECIFIED = 0;
TOOL_KIND_FUNCTION = 1;
TOOL_KIND_FREEFORM = 2;
}
message ContentItem {
oneof item {
TextContent text = 1;
ImageContent image = 2;
AudioContent audio = 3;
}
}
message TextContent {
string text = 1;
}
message ImageContent {
string image_url = 1;
optional ImageDetail detail = 2;
}
message AudioContent {
string audio_url = 1;
}
enum ImageDetail {
IMAGE_DETAIL_UNSPECIFIED = 0;
IMAGE_DETAIL_AUTO = 1;
IMAGE_DETAIL_LOW = 2;
IMAGE_DETAIL_HIGH = 3;
IMAGE_DETAIL_ORIGINAL = 4;
}