// Copyright 2026 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

option optimize_for = LITE_RUNTIME;

package browser_actuator;

import "google/protobuf/any.proto";

// These mirror the internal transport channel message protos. Do not modify
// without updating the corresponding protos.

// Payload for a control command that is processed internally by the channel
// (when the PayloadType is `..._CONTROL_COMMAND` typed).
message ControlCommand {
  oneof command {
    CloseChannel close_channel = 1;
    CloseSession close_session = 2;
  }
  // Closes the channel between the client and the server.
  message CloseChannel {}

  // Closes an active agent session or task between the Chrome client and the
  // server. The session is identified by the session_id in the envelope
  // message.
  message CloseSession {}
}

// Identifies the routing destination in the server of an
// ActuatorUpstreamMessage.
enum ActuatorUpstreamPayloadType {
  // Default value. Should not be used.
  ACTUATOR_UPSTREAM_PAYLOAD_TYPE_UNSPECIFIED = 0;
  // Channel control command, e.g. destroy channel or close session.
  ACTUATOR_UPSTREAM_PAYLOAD_TYPE_CONTROL_COMMAND = 1;
  // Legacy experimental triggering message.
  ACTUATOR_UPSTREAM_PAYLOAD_TYPE_EXPERIMENTAL_TRIGGERING = 2;
}

// Wrapper that pairs a payload with its routing type.
// This message is passed through the channel to the server side.
message ActuatorUpstreamTypedPayload {
  // Core payload sent from the Chrome client.
  google.protobuf.Any proto_payload = 1;
  // Used to direct the message to the correct feature team in Agency.
  ActuatorUpstreamPayloadType payload_type = 2;
}

// Information from the Chrome client that is stored and received by the
// server-side transport library.
message ActuatorUpstreamMessage {
  // Unique identifier for the active agent session or task.
  string session_id = 1;

  // Monotonically increasing sequence number generated by the client used to
  // order independent and responding messages.  Sequence numbers start at 1.
  int64 client_sequence_number = 2;

  // Sequence number of the ActuatorDownstreamMessage this message correlates
  // to, if it is responding to a ActuatorDownstreamMessage.
  optional int64 responding_to_sequence_number = 3;

  // Describes the capabilities and version of the browser actuator in Chrome.
  message BrowserActuatorCapabilities {
    // Chrome major version number.
    int64 chrome_major_version_number = 1;
    // List of active browser actuator features supported by the Chrome client.
    repeated string supported_features = 2;
  }
  // Versioning and browser actuator capabilities of the target client.
  BrowserActuatorCapabilities capabilities = 4;

  // Typed payloads with the intended endpoint feature on the server.
  repeated ActuatorUpstreamTypedPayload typed_payloads = 5;
}

// Identifies the routing destination in the Chrome client of an
// ActuatorDownstreamMessage.
enum ActuatorDownstreamPayloadType {
  // Default value.
  ACTUATOR_DOWNSTREAM_PAYLOAD_TYPE_UNSPECIFIED = 0;
  // Channel control command, e.g. destroy channel or close session.
  ACTUATOR_DOWNSTREAM_PAYLOAD_TYPE_CONTROL_COMMAND = 1;
  // Legacy experimental triggering message.
  ACTUATOR_DOWNSTREAM_PAYLOAD_TYPE_EXPERIMENTAL_TRIGGERING = 2;
}

// Wrapper that pairs a payload with its routing type.
// This message is passed through the channel to the Chrome client.
message ActuatorDownstreamTypedPayload {
  // Eventual payload delivered by the transport library to the target
  // feature handler in Chrome.
  google.protobuf.Any proto_payload = 1;
  // Used to direct the message to the correct feature team's handler in Chrome.
  ActuatorDownstreamPayloadType payload_type = 2;
}

// Information sent from OnePlatform or the server down to the Chrome client
// over the active session stream.
message ActuatorDownstreamMessage {
  // Unique identifier for the active agent session or task.
  string session_id = 1;

  // Monotonic sequence number used for ordering and connection resumption.
  // Sequence numbers start at 1.
  int64 sequence_number = 2;

  // Typed payloads with the intended target feature handler in Chrome.
  repeated ActuatorDownstreamTypedPayload typed_payloads = 3;
}

// Body uploaded with the (re)connection request that opens the downstream
// stream. Names the sessions the client wants to watch and, per session, the
// resume position so the server can replay anything missed since the last
// connection.
message WatchSessionsRequest {
  // Unique identifier for this request used by the server for
  // idempotency and retry deduplication.
  string request_id = 1;

  // The sessions that the client is watching.
  repeated Session sessions = 2;
  message Session {
    // Unique identifier for the session.
    string session_id = 1;
    // The sequence number of the last seen downstream message.
    int64 last_seen_sequence_number = 2;
  }
}

// Request message for SendSessionMessage RPC.
message SendSessionMessageRequest {
  // Unique identifier for this request used by the server for
  // idempotency and retry deduplication.
  string request_id = 1;

  // The upstream message payload sent from the Chrome client.
  ActuatorUpstreamMessage actuator_upstream_message = 2;
}

// Response message for SendSessionMessage RPC.
message SendSessionMessageResponse {}
// Response messages streamed by WatchSessions RPC.
message WatchSessionsResponse {
  // The downstream message payload sent from the server to the Chrome client.
  ActuatorDownstreamMessage actuator_downstream_message = 1;
}