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; }