mirror of
https://github.com/openai/codex.git
synced 2026-11-16 22:00:36 +00:00
## 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
336 lines
9.3 KiB
Protocol Buffer
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;
|
|
}
|