api.proto

syntax = "proto2";
option objc_class_prefix = "ITM";
package api;

// A note on session IDs:
// In requests, session IDs may take one of three values;
// 1. A unique ID as returned in ListSessionsResponse
// 2. The special value "all", which applies to all sessions. This is sometimes not accepted. See
//    comments in the request message for details.
// 3. The special value "active", which applies to the session with keyboard focus.

// All requests are wrapped in this message. This encoded message is the entirety of the payload
// of messages sent over WebSocket from client to iTerm2.
message ClientOriginatedMessage {
  optional int64 id = 1;

  oneof submessage {
    GetBufferRequest get_buffer_request = 100;
    GetPromptRequest get_prompt_request = 101;
    TransactionRequest transaction_request = 102;
    NotificationRequest notification_request = 103;
    RegisterToolRequest register_tool_request = 104;
    SetProfilePropertyRequest set_profile_property_request = 105;
    ListSessionsRequest list_sessions_request = 106;
    SendTextRequest send_text_request = 107;
    CreateTabRequest create_tab_request = 108;
    SplitPaneRequest split_pane_request = 109;
    GetProfilePropertyRequest get_profile_property_request = 110;
    SetPropertyRequest set_property_request = 111;
    GetPropertyRequest get_property_request = 112;
    InjectRequest inject_request = 113;
    ActivateRequest activate_request = 114;
    VariableRequest variable_request = 115;
    SavedArrangementRequest saved_arrangement_request = 116;
    FocusRequest focus_request = 117;
    ListProfilesRequest list_profiles_request = 118;
    ServerOriginatedRPCResultRequest server_originated_rpc_result_request = 119;
    RestartSessionRequest restart_session_request = 120;
    MenuItemRequest menu_item_request = 121;
    SetTabLayoutRequest set_tab_layout_request = 122;
    GetBroadcastDomainsRequest get_broadcast_domains_request = 123;
    TmuxRequest tmux_request = 124;
    ReorderTabsRequest reorder_tabs_request = 125;
    PreferencesRequest preferences_request = 126;
    ColorPresetRequest color_preset_request = 127;
    SelectionRequest selection_request = 128;
    StatusBarComponentRequest status_bar_component_request = 129;
    SetBroadcastDomainsRequest set_broadcast_domains_request = 130;
    CloseRequest close_request = 131;
    InvokeFunctionRequest invoke_function_request = 132;
  }
}

// All responses are wrapped in this message. This encoded message is the entirety of the payload
// of messages sent over WebSocket from iTerm2 to client.
message ServerOriginatedMessage {
  optional int64 id = 1;

  // Responses to ClientOriginatedMessages of the corresponding type
  oneof submessage {
    string error = 2;  // Set if request was malformed

    GetBufferResponse get_buffer_response = 100;
    GetPromptResponse get_prompt_response = 101;
    TransactionResponse transaction_response = 102;
    NotificationResponse notification_response = 103;
    RegisterToolResponse register_tool_response = 104;
    SetProfilePropertyResponse set_profile_property_response = 105;
    ListSessionsResponse list_sessions_response = 106;
    SendTextResponse send_text_response = 107;
    CreateTabResponse create_tab_response = 108;
    SplitPaneResponse split_pane_response = 109;
    GetProfilePropertyResponse get_profile_property_response = 110;
    SetPropertyResponse set_property_response = 111;
    GetPropertyResponse get_property_response = 112;
    InjectResponse inject_response = 113;
    ActivateResponse activate_response = 114;
    VariableResponse variable_response = 115;
    SavedArrangementResponse saved_arrangement_response = 116;
    FocusResponse focus_response = 117;
    ListProfilesResponse list_profiles_response = 118;
    ServerOriginatedRPCResultResponse server_originated_rpc_result_response = 119;
    RestartSessionResponse restart_session_response = 120;
    MenuItemResponse menu_item_response = 121;
    SetTabLayoutResponse set_tab_layout_response = 122;
    GetBroadcastDomainsResponse get_broadcast_domains_response = 123;
    TmuxResponse tmux_response = 124;
    ReorderTabsResponse reorder_tabs_response = 125;
    PreferencesResponse preferences_response = 126;
    ColorPresetResponse color_preset_response = 127;
    SelectionResponse selection_response = 128;
    StatusBarComponentResponse status_bar_component_response = 129;
    SetBroadcastDomainsResponse set_broadcast_domains_response = 130;
    CloseResponse close_response = 131;
    InvokeFunctionResponse invoke_function_response = 132;

    // This is the only response that is sent spontaneously. The 'id' field will not be set.
    Notification notification = 1000;
  }
}

message InvokeFunctionRequest {
  message Tab {
    optional string tab_id = 1;
  }
  message Session {
    optional string session_id = 1;
  }
  message Window {
    optional string window_id = 1;
  }
  message App {
  }
  message Method {
    optional string receiver = 1;
  }
  oneof context {
    Tab tab = 1;
    Session session = 2;
    Window window = 3;
    App app = 4;
    Method method = 7;
  }
  optional string invocation = 5;
  optional double timeout = 6 [default=-1];  // If not given a reasonable default value will be used. Negative value means to use the default.
}

message InvokeFunctionResponse {
  enum Status {
    TIMEOUT = 1;
    FAILED = 2;
    REQUEST_MALFORMED = 3;
    INVALID_ID = 4;
  }
  message Error {
    optional Status status = 1;
    optional string error_reason = 2;
  }
  message Success {
    optional string json_result = 1;
  }
  oneof disposition {
    Error error = 1;
    Success success = 2;
  }
}

message CloseRequest {
  message CloseTabs {
    repeated string tab_ids = 1;
  }
  message CloseSessions {
    repeated string session_ids = 1;
  }
  message CloseWindows {
    repeated string window_ids = 1;
  }
  oneof target {
    CloseTabs tabs = 1;
    CloseSessions sessions = 2;
    CloseWindows windows = 3;
  }
  optional bool force = 4;
}

message CloseResponse {
  enum Status {
    OK = 0;
    NOT_FOUND = 1;
    USER_DECLINED = 2;
  }
  repeated Status statuses = 1;
}

message SetBroadcastDomainsRequest {
  repeated BroadcastDomain broadcast_domains = 1;
}

message SetBroadcastDomainsResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
    BROADCAST_DOMAINS_NOT_DISJOINT = 2;
    SESSIONS_NOT_IN_SAME_WINDOW = 3;
  }
  optional Status status = 1;
}

message StatusBarComponentRequest {
  message OpenPopover {
    optional string session_id = 1;
    optional string html = 2;  // HTML to show in a popover that opens from the component.
    optional Size size = 3;  // Size in points of the content area of the popover.
  }
  oneof request {
    OpenPopover open_popover = 1;
  }
  optional string identifier = 2;  // ID of statusbar component
}

message StatusBarComponentResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
    REQUEST_MALFORMED = 2;
    INVALID_IDENTIFIER = 3;
  }
  optional Status status = 1;
}

message WindowedCoordRange {
  optional CoordRange coord_range = 1;
  optional Range columns = 2;
}

enum SelectionMode {
  CHARACTER = 0;
  WORD = 1;
  LINE = 2;
  SMART = 3;
  BOX = 4;
  WHOLE_LINE = 5;
}

message SubSelection {
  optional WindowedCoordRange windowed_coord_range = 1;
  optional SelectionMode selection_mode = 2;
  optional bool connected = 3;
}

message Selection {
  repeated SubSelection sub_selections = 1;
}

message SelectionRequest {
  message GetSelectionRequest {
    optional string session_id = 1;
  }
  message SetSelectionRequest {
    optional string session_id = 1;
    optional Selection selection = 2;
  }
  oneof request {
    GetSelectionRequest get_selection_request = 1;
    SetSelectionRequest set_selection_request = 2;
  }
}

message SelectionResponse {
  enum Status {
    OK = 0;
    INVALID_SESSION = 1;
    INVALID_RANGE = 2;
    REQUEST_MALFORMED = 3;
  }
  optional Status status = 1;
  message GetSelectionResponse {
    optional Selection selection = 2;
  }
  message SetSelectionResponse {
  }
  oneof response {
    GetSelectionResponse get_selection_response = 2;
    SetSelectionResponse set_selection_response = 3;
  }
}

message ColorPresetRequest {
  message ListPresets {
  }
  message GetPreset {
    optional string name = 1;
  }
  oneof request {
    ListPresets list_presets = 1;
    GetPreset get_preset = 2;
  }
}

message ColorPresetResponse {
  message ListPresets {
    repeated string name = 1;
  }

  message GetPreset {
    message ColorSetting {
      optional float red = 1;
      optional float green = 2;
      optional float blue = 3;
      optional float alpha = 4;
      optional string color_space = 5;
      optional string key = 6;
    }
    repeated ColorSetting color_settings = 1;
  }

  oneof response {
    ListPresets list_presets = 1;
    GetPreset get_preset = 2;
  }

  enum Status {
    OK = 0;
    PRESET_NOT_FOUND = 1;
    REQUEST_MALFORMED = 2;
  }
  optional Status status = 3;
}

message PreferencesRequest {
  message Request {
    message SetPreference {
      optional string key = 1;
      optional string json_value = 2;
    }
    message GetPreference {
      optional string key = 1;
    }
    message SetDefaultProfile {
      optional string guid = 1;
    }
    oneof request {
      SetPreference set_preference_request = 1;
      GetPreference get_preference_request = 2;
      SetDefaultProfile set_default_profile_request = 3;
    }
  }
  repeated Request requests = 1;
}

message PreferencesResponse {
  message Result {
    message SetPreferenceResult {
      enum Status {
        OK = 0;
        BAD_JSON = 1;
        INVALID_VALUE = 2;  // Not legal for a plist
      }
      optional Status status = 1;
    }
    message GetPreferenceResult {
      optional string json_value = 1;  // Will be unset if no value assigned. Will always be set if there is a default value.
    }
    message SetDefaultProfileResult {
      enum Status {
        OK = 0;
        BAD_GUID = 1;
      }
      optional Status status = 1;
    }
    message UnrecognizedResult {
    }
    oneof result {
      UnrecognizedResult unrecognized_request = 1;
      SetPreferenceResult set_preference_result = 2;
      GetPreferenceResult get_preference_result = 3;
      SetDefaultProfileResult set_default_profile_result = 4;
    }
  }
  repeated Result results = 1;
}

message ReorderTabsRequest {
  message Assignment {
    optional string window_id = 1;
    repeated string tab_ids = 2;
  }
  repeated Assignment assignments = 3;
}

message ReorderTabsResponse {
  enum Status {
    OK = 0;
    INVALID_ASSIGNMENT = 1;  // e.g., duplicate tab id
    INVALID_WINDOW_ID = 2;
    INVALID_TAB_ID = 3;
  }
  optional Status status = 4;
}

message TmuxRequest {
  message ListConnections {
  }
  message SendCommand {
    optional string connection_id = 1;
    optional string command = 2;
  }
  message SetWindowVisible {
    optional string connection_id = 1;
    optional string window_id = 2;
    optional bool visible = 3;
  }
  message CreateWindow {
    optional string connection_id = 1;
    optional string affinity = 2;
  }
  oneof payload {
    ListConnections list_connections = 1;
    SendCommand send_command = 2;
    SetWindowVisible set_window_visible = 3;
    CreateWindow create_window = 4;
  }
}

message TmuxResponse {
  message ListConnections {
    message Connection {
      optional string connection_id = 1;
      optional string owning_session_id = 2;
    }
    repeated Connection connections = 1;
  }
  message SendCommand {
    // If not set, an error occurred.
    optional string output = 1;
  }
  message SetWindowVisible {
  }
  message CreateWindow {
    // This is an iTerm2 tab ID.
    optional string tab_id = 1;
  }
  oneof payload {
    ListConnections list_connections = 1;
    SendCommand send_command = 2;
    SetWindowVisible set_window_visible = 3;
    CreateWindow create_window = 5;
  }

  enum Status{
    OK = 0;
    INVALID_REQUEST = 1;
    INVALID_CONNECTION_ID = 2;
    INVALID_WINDOW_ID = 3;
  }
  optional Status status = 4;
}

message GetBroadcastDomainsRequest {
}

message BroadcastDomain {
  repeated string session_ids = 1;
}

message GetBroadcastDomainsResponse {
  repeated BroadcastDomain broadcast_domains = 1;
}

message SetTabLayoutRequest {
  // The tree structure must exactly match the actual tree structure, including the `vertical`
  // setting. Only the grid_sizes may change. They must still add up to the same value in every
  // dimension.
  optional SplitTreeNode root = 1;
  optional string tab_id = 2;
}

message SetTabLayoutResponse {
  enum Status {
    OK = 0;
    BAD_TAB_ID = 1;
    WRONG_TREE = 2;
    INVALID_SIZE = 3;
  }
  optional Status status = 1;
}

// Invoke or ask for info about a menu item
message MenuItemRequest {
  // Unique identifier of the menu item.
  optional string identifier = 1;

  // If set do not actually invoke it. Just return its state.
  optional bool query_only = 2;
}

message MenuItemResponse {
  enum Status {
    OK = 0;
    BAD_IDENTIFIER = 1;
    DISABLED = 2;
  }
  optional Status status = 1;
  optional bool checked = 2;
  optional bool enabled = 3;
}

message RestartSessionRequest {
  optional string session_id = 1;  // "all" not allowed.

  // If set, then still-running sessions will fail to restart with SESSION_NOT_RESTARTABLE.
  // If not set, then a still-running session gets killed and restarted.
  optional bool only_if_exited = 2;
}

message RestartSessionResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;

    // Some sessions, such as tmux integration sessions, are not restartable.
    // Also, when `only_if_exited` is set in the request and the session is still running then this
    // status will be returned.
    SESSION_NOT_RESTARTABLE = 2;
  }
  optional Status status = 1;
}

// This is the result of an iTerm2-to-script RPC call.
message ServerOriginatedRPCResultRequest {
  optional string request_id = 1;
  oneof result {
    // Exceptions should be dictionaries with a key of "reason" having a string value describing
    // what went wrong.
    string json_exception = 2;
    string json_value = 3;
  }
}

// This simply acknowledges receipt of ServerOriginatedRPCResultRequest.
message ServerOriginatedRPCResultResponse {
}

// Requests a list of all profiles.
message ListProfilesRequest {
    // The profile properties to respond with. See SetProfilePropertyRequest for a list of values.
    // If empty, all properties will be returned.
    repeated string properties = 1;

    // If empty, all profiles will be returned. Otherwise, only profiles with one of the listed
    // GUIDs will be returned.
    repeated string guids = 2;
}

message ListProfilesResponse {
    message Profile {
        repeated ProfileProperty properties = 1;
    }
    repeated Profile profiles = 1;
}

message FocusRequest {
}

message FocusResponse {
  // A collection of notifications that completely describe the state of every tab and window and
  // the application itself.
  repeated FocusChangedNotification notifications = 1;
}

message SavedArrangementRequest {
  optional string name = 1;
  enum Action {
    // Restore an existing arrangement with the given name
    RESTORE = 0;

    // Save windows to a new arrangement with the given name
    SAVE = 1;
  }
  optional Action action = 2;

  // If given and the action is SAVE then only the tabs in the identified window are saved.
  // If given and the action is RESTORE then the arrangement will be restored as tabs in the identified window.
  optional string window_id = 3;
}

message SavedArrangementResponse {
  enum Status {
    OK = 0;
    ARRANGEMENT_NOT_FOUND = 1;  // Tried to restore, but name doesn't exist
    WINDOW_NOT_FOUND = 2;  // Bad window ID provided
    REQUEST_MALFORMED = 3;
  }
  optional Status status = 1;
}

message VariableRequest {
  oneof scope {
    string session_id = 1;  // "all" is allowed only if no gets (only sets allowed)
    string tab_id = 4;  // "all" is allowed only if no gets (only sets allowed)
    bool app = 5;
    string window_id = 6;  // "all" is allowed only if no gets (only sets allowed)
  }

  message Set {
    optional string name = 1;
    optional string value = 2;  // JSON encoded
  }
  repeated Set set = 2;
  repeated string get = 3;  // Set to special value "*" to get all in a JSON dictionary
}

message VariableResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
    INVALID_NAME = 2;  // Names you set must begin with "user."
    MISSING_SCOPE = 3;  // None of the scope oneof fields was set
    TAB_NOT_FOUND = 4;
    MULTI_GET_DISALLOWED = 5;
    WINDOW_NOT_FOUND = 6;
  }
  optional Status status = 1;
  repeated string values = 2;  // 1:1 with get field in request.  JSON encoded, with null for unset variables.
}

message ActivateRequest {
  // To activate the app without changing anything else omit the identifier.
  oneof identifier {
    string window_id = 1;
    string tab_id = 2;
    string session_id = 3;
  }
  optional bool order_window_front = 4;

  // This may be enabled if tab_id or session_id is set.
  optional bool select_tab = 5;

  // This may be enabled if session_id is set.
  optional bool select_session = 6;

  // Activate the app?
  message App {
    optional bool raise_all_windows = 1;
    optional bool ignoring_other_apps = 2;
  }
  optional App activate_app = 7;
}

message ActivateResponse {
  enum Status {
    OK = 0;
    BAD_IDENTIFIER = 1;
    INVALID_OPTION = 2;
  }
  optional Status status = 1;
}

// Injects bytes as input to the terminal, as though the running program had produced them.
message InjectRequest {
  repeated string session_id = 1;
  optional bytes data = 2;
}

message InjectResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
  }
  // One status per session_id in the request
  repeated Status status = 1;
}

message GetPropertyRequest {
  // The kind of ID that's set determines the kind of object you're querying.
  oneof identifier {
    string window_id = 1;
    string session_id = 3;  // Does not accept "all". Accepts "active".
  }
  // For sessions:
  // "grid_size" -> { "width": number, "height": number }
  // "buried" -> boolean
  // "number_of_lines" -> { "overflow": number, "grid": number, "history": number }
  //
  // For windows:
  // "frame" -> { "origin": { "x": number, "y": number }, "size": { "width": number, "height": number } }
  // "fullscreen" -> boolean
  optional string name = 2;
}

message GetPropertyResponse {
  enum Status {
    OK = 0;
    UNRECOGNIZED_NAME = 1;
    INVALID_TARGET = 2;
  }
  // Name           Example value
  // -------------  ---------------
  // frame          { "origin": { "x": 0, "y": 0 }, "size": { "width": 1024, "height": 768 }}
  // fullscreen     true, false
  //
  // For sessions:
  // grid_size      { "width": 80, "height": 25 }
  // buried         true
  optional Status status = 1;
  optional string json_value = 2;
}

message SetPropertyRequest {
  // Eventually you'll be able to set properties on other things besides The kind of ID that's set
  // determines the kind of object you're updating.
  oneof identifier {
    string window_id = 1;
    string session_id = 5;  // Accepts "all" and "active"
  }
  // For windows:
  // Name           Example JSON
  // -------------  ---------------
  // frame          { "origin": { "x": 0, "y": 0 }, "size": { "width": 1024, "height": 768 }}
  // fullscreen     true, false
  //
  // For sessions:
  // grid_size      { "width": 80, "height": 25 }
  // buried         true
  optional string name = 3;
  optional string json_value = 4;
}

message SetPropertyResponse {
  enum Status {
    OK = 0;
    UNRECOGNIZED_NAME = 1;
    INVALID_VALUE = 2;  // e.g., bad JSON value
    INVALID_TARGET = 3;  // e.g., bogus window_id
    DEFERRED = 4;  // Operation can't be performed immediately. Will be tried later. For example, resizing a session during instant replay.
    IMPOSSIBLE = 5;  // Can't be done. For example, resizing a session in a full-screen window.
    FAILED = 6;  // Did our best and failed. For example, sometimes toggling full-screen fails if another window is also toggling. Maybe try again?
  }
  optional Status status = 1;
}

// Registers a toolbelt tool that displays a webview with a URL of your choice.
message RegisterToolRequest {
  // This name is displayed to the user.
  optional string name = 1;

  // The tool's identifier should be unique. Prefix it with your app bundle. For example:
  // com.example.mytool
  optional string identifier = 2;

  enum ToolType {
    WEB_VIEW_TOOL = 1;
  }

  // The first time a tool is registered iTerm2 automatically adds it to the
  // set of visible tools. To show it on subsequent re-registrations, set this
  // to true. If the toolbelt itself is hidden, it will not be opened.
  optional bool reveal_if_already_registered = 5 [default = false];

  optional ToolType tool_type = 3 [default = WEB_VIEW_TOOL];

  // For web view tools: The URL loaded at startup
  optional string URL = 4;
}

// Describes an RPC from iTerm2 to script. I don't want to invent my own type
// system so this is dynamically typed, which matches Python well enough.
message RPCRegistrationRequest {
  message RPCArgumentSignature {
    optional string name = 1;
  }
  optional string name = 1;
  repeated RPCArgumentSignature arguments = 2;

  message RPCArgument {
    optional string name = 1;
    optional string path = 2;
  }
  repeated RPCArgument defaults = 4;

  // If not specified, iTerm2 decides based on its built-in default.
  optional float timeout = 3;

  enum Role {
    GENERIC = 1;
    SESSION_TITLE = 2;
    STATUS_BAR_COMPONENT = 3;
  }
  optional Role role = 5 [default=GENERIC];

  message SessionTitleAttributes {
    // Used by SESSION_TITLE to control name in Preferences menu
    optional string display_name = 1;
    // Identifies this title provider uniquely. Must not conflict with other title providers.
    // Use a backwards domain name identifying yourself and the feature, like "com.example.featurename"
    optional string unique_identifier = 6;
  }
  message StatusBarComponentAttributes {
    // Used by STATUS_BAR_COMPONENT
    optional string short_description = 1;
    optional string detailed_description = 2;

    message Knob {
      optional string name = 1;
      enum Type {
        Checkbox = 1;
        String = 2;
        PositiveFloatingPoint = 3;
        Color = 4;
      }
      optional Type type = 2;
      optional string placeholder = 3;
      optional string json_default_value = 4;
      optional string key = 5;
    }
    repeated Knob knobs = 3;

    optional string exemplar = 4;
    optional float update_cadence = 5;

    // Identifies this component uniquely. Must not conflict with other components.
    // Use a backwards domain name identifying yourself and the feature, like "com.example.featurename"
    optional string unique_identifier = 6;

    message Icon {
      optional bytes data = 1;
      optional float scale = 2;
    }
    repeated Icon icons = 7;
  }

  oneof RoleSpecificAttributes {
    SessionTitleAttributes session_title_attributes = 7;
    StatusBarComponentAttributes status_bar_component_attributes = 8;
  }

  optional string display_name = 6 [deprecated=true];
}

message RegisterToolResponse {
  enum Status {
    OK = 0;
    REQUEST_MALFORMED = 1;
    PERMISSION_DENIED = 2;
  }

  optional Status status = 1;
}

enum NotificationType {
  // Notifications that use the `session` parameter.
  NOTIFY_ON_KEYSTROKE = 1;
  NOTIFY_ON_SCREEN_UPDATE = 2;
  NOTIFY_ON_PROMPT = 3;
  NOTIFY_ON_LOCATION_CHANGE = 4 [deprecated=true];
  NOTIFY_ON_CUSTOM_ESCAPE_SEQUENCE = 5;
  NOTIFY_ON_VARIABLE_CHANGE = 12;
  KEYSTROKE_FILTER = 14;  // Does not send a notification

  // Notifications that ignore the `session` parameter.
  NOTIFY_ON_NEW_SESSION = 6;
  NOTIFY_ON_TERMINATE_SESSION = 7;
  NOTIFY_ON_LAYOUT_CHANGE = 8;
  NOTIFY_ON_FOCUS_CHANGE = 9;
  NOTIFY_ON_SERVER_ORIGINATED_RPC = 10;
  NOTIFY_ON_BROADCAST_CHANGE = 11;
  NOTIFY_ON_PROFILE_CHANGE = 13;
}

enum Modifiers {
  CONTROL = 1;
  OPTION = 2;
  COMMAND = 3;
  SHIFT = 4;
  FUNCTION = 5;
  NUMPAD = 6;
}

message KeystrokePattern {
  // The keystroke matches the pattern if it has all the required and none of the forbidden modifiers.
  repeated Modifiers required_modifiers = 1;
  repeated Modifiers forbidden_modifiers = 2;

  // The pattern matches if the keystroke has any of these keycodes:
  repeated int32 keycodes = 3;

  // The pattern matches if the keystroke equals of any of these characters:
  repeated string characters = 4;

  // The pattern matches if the keystroke equals any of these characters ignoring modifiers.
  // This is Apple parlance for "ignoring the shift key plus various other undocumented things"
  repeated string characters_ignoring_modifiers = 5;
}

message KeystrokeMonitorRequest {
  // KeystrokeFilterRequest was split from this to make a more sensible API.
  repeated KeystrokePattern patterns_to_ignore = 1 [deprecated=true];
}

message KeystrokeFilterRequest {
  // If a keystroke matches any of these patterns then they will not be handled by the application.
  // A notification will be posted and the script can handle it as it pleases.
  repeated KeystrokePattern patterns_to_ignore = 1;
}

enum VariableScope {
  SESSION = 1;
  TAB = 2;
  WINDOW = 3;
  APP = 4;
}

message VariableMonitorRequest {
  optional string name = 1;
  optional VariableScope scope = 2;
  optional string identifier = 3;  // Session, Window, or Tab identifier.
}

message ProfileChangeRequest {
  optional string guid = 1;
}

enum PromptMonitorMode {
  PROMPT = 1;
  COMMAND_START = 2;
  COMMAND_END = 3;
}

message PromptMonitorRequest {
  repeated PromptMonitorMode modes = 1;
}

message NotificationRequest {
  // See documentation on session IDs. NOTIFY_ON_NEW_SESSION, NOTIFY_ON_TERMINATE_SESSION, and
  // NOTIFY_ON_LAYOUT_CHANGE do not use the session ID and are posted on all such events.
  //
  // NOTE: This is not used for NOTIFY_ON_VARIABLE_CHANGE.
  optional string session = 1;

  // Set to true to subscribe, false to unsubscribe.
  optional bool subscribe = 2;

  // When to be notified (or notification to unsubscribe from)
  optional NotificationType notification_type = 3;

  oneof arguments {
    RPCRegistrationRequest rpc_registration_request = 4;  // For NOTIFY_ON_SERVER_ORIGINATED_RPC
    KeystrokeMonitorRequest keystroke_monitor_request = 5;
    VariableMonitorRequest variable_monitor_request = 6;
    ProfileChangeRequest profile_change_request = 7;
    KeystrokeFilterRequest keystroke_filter_request = 8;
    PromptMonitorRequest prompt_monitor_request = 9;
  }
}

message NotificationResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
    REQUEST_MALFORMED = 2;
    NOT_SUBSCRIBED = 3;
    ALREADY_SUBSCRIBED = 4;
    DUPLICATE_SERVER_ORIGINATED_RPC = 5;
    INVALID_IDENTIFIER = 6;
  }
  optional Status status = 1;
}

message Notification {
  optional KeystrokeNotification keystroke_notification = 1;
  optional ScreenUpdateNotification screen_update_notification = 2;
  optional PromptNotification prompt_notification = 3;
  optional LocationChangeNotification location_change_notification = 4 [deprecated=true];
  optional CustomEscapeSequenceNotification custom_escape_sequence_notification = 5;
  optional NewSessionNotification new_session_notification = 6;
  optional TerminateSessionNotification terminate_session_notification = 7;
  optional LayoutChangedNotification layout_changed_notification = 8;
  optional FocusChangedNotification focus_changed_notification = 9;
  optional ServerOriginatedRPCNotification server_originated_rpc_notification = 10;
  optional BroadcastDomainsChangedNotification broadcast_domains_changed = 11;
  optional VariableChangedNotification variable_changed_notification = 12;
  optional ProfileChangedNotification profile_changed_notification = 13;
}

message ProfileChangedNotification {
  optional string guid = 1;
}

message VariableChangedNotification {
  optional VariableScope scope = 1;
  optional string identifier = 2;  // unset if app scope, otherwise is session, window, or tab ID
  optional string name = 3;
  optional string json_new_value = 4;  // Will be "null" if unset.
}

message BroadcastDomainsChangedNotification {
  repeated BroadcastDomain broadcast_domains = 1;
}

message ServerOriginatedRPC {
  message RPCArgument {
    optional string name = 1;
    optional string json_value = 2;
  }
  optional string name = 2;
  repeated RPCArgument arguments = 3;
}

// This is an iTerm2-to-script RPC call. The script must have registered for
// an RPC matching the signature of `rpc`.
message ServerOriginatedRPCNotification {
  optional string request_id = 1;
  optional ServerOriginatedRPC rpc = 2;
}

message KeystrokeNotification {
  optional string characters = 1;
  optional string charactersIgnoringModifiers = 2;
  repeated Modifiers modifiers = 3;
  optional int32 keyCode = 4;
  optional string session = 5;
}

message ScreenUpdateNotification {
  optional string session = 1;
}

message PromptNotificationPrompt {
  optional string placeholder = 1;
}

message PromptNotificationCommandStart {
  optional string command = 1;
}

message PromptNotificationCommandEnd {
  optional int32 status = 1;
}

message PromptNotification {
  optional string session = 1;
  oneof event {
    PromptNotificationPrompt prompt = 2;
    PromptNotificationCommandStart command_start = 3;
    PromptNotificationCommandEnd command_end = 4;
  }
}

message LocationChangeNotification {
  optional string host_name = 1;
  optional string user_name = 2;
  optional string directory = 3;
  optional string session = 4;
}

// OSC 1337 ; Custom=id=<identity>:<payload> ST
message CustomEscapeSequenceNotification {
  optional string session = 1;
  optional string sender_identity = 2;
  optional string payload = 3;
}

// Sent when a new session is created or a closure is undone.
message NewSessionNotification {
  optional string session_id = 1;
}

// Note this is sent when the app becomes/resigns active, the key window changes, the selected tab
// of a window changes, or the active pane of a tab changes. Note that you may receive duplicate
// notifications at times. Ignore those that do not signify a change.
message FocusChangedNotification {
  message Window {
    enum WindowStatus {
      // `window_id` became key
      TERMINAL_WINDOW_BECAME_KEY = 0;

      // `window_id` is not key, but is the current terminal window. Some other non-terminal window is key.
      TERMINAL_WINDOW_IS_CURRENT = 1;

      // `window_id` is no longer key.
      TERMINAL_WINDOW_RESIGNED_KEY = 2;
    }
    // Describes how to interpret window_id.
    optional WindowStatus window_status = 1;

    // The affected window_id
    optional string window_id = 2;
  }
  oneof event {
    // true: application became active. false: application resigned active.
    bool application_active = 1;

    // If set, gives info about a change to window focus.
    Window window = 2;

    // If set, selected tab changed to the one identified herein.
    string selected_tab = 3;

    // If set, the given session became active in its tab.
    string session = 4;
  }
}

message TerminateSessionNotification {
  optional string session_id = 1;
}

message LayoutChangedNotification {
  optional ListSessionsResponse list_sessions_response = 1;
}

// Requests the contents of a range of lines.
message GetBufferRequest {
  // See documentation on session IDs. "all" not accepted.
  optional string session = 1;

  // Which lines to return?
  optional LineRange line_range = 2;
}

// Contains the contents of a range of lines.
message GetBufferResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
    INVALID_LINE_RANGE = 2;
    REQUEST_MALFORMED = 3;
  }

  optional Status status = 1 [default = OK];

  // Which lines were returned
  optional Range range = 2 [deprecated=true];

  // Those lines' contents.
  repeated LineContents contents = 3;

  optional Coord cursor = 4;

  // The number of lines (including lines lost from the head of scrollback history) that precede
  // the screen. Subtract this from cursor.y to get the cursor's position on the screen when it
  // is scrolled to the bottom.
  optional int64 num_lines_above_screen = 5 [deprecated=true];

  // The returned range
  optional WindowedCoordRange windowed_coord_range = 6;
}

// Requests metadata about the current shell prompt.
message GetPromptRequest {
  // See documentation on session IDs. "all" not accepted.
  optional string session = 1;
}

// Responds with metadata about the current shell prompt, if possible.
message GetPromptResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
    REQUEST_MALFORMED = 2;
    PROMPT_UNAVAILABLE = 3;
  }

  optional Status status = 1 [default = OK];

  optional CoordRange prompt_range = 2;
  optional CoordRange command_range = 3;
  optional CoordRange output_range = 4;

  optional string working_directory = 5;
  optional string command = 6;
}

message GetProfilePropertyRequest {
  // See documentation on session IDs
  optional string session = 1;

  // If not set, all properties will be returned
  repeated string keys = 2;
}

message ProfileProperty {
    optional string key = 1;
    optional string json_value = 2;
}

message GetProfilePropertyResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
    REQUEST_MALFORMED = 2;
    ERROR = 3;
  }

  optional Status status = 1 [default = OK];

  repeated ProfileProperty properties = 3;
}

// Sets a value in a session's copy of the profile without modifying the underlying profile.
message SetProfilePropertyRequest {
  message GuidList {
    repeated string guids = 1;
  }
  oneof target {
    // See documentation on session IDs
    string session = 1;
    GuidList guid_list = 2;
  }

  optional string key = 3;  // deprecated
  optional string json_value = 4;  // deprecated

  message Assignment {
    optional string key = 1;
    optional string json_value = 2;
  }
  repeated Assignment assignments = 5;
}

message SetProfilePropertyResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
    REQUEST_MALFORMED = 2;
    BAD_GUID = 3;
  }

  optional Status status = 1 [default = OK];
}

message TransactionRequest {
  // Set to true to begin a new transaction or false to end the current
  // transaction. The app's main loop will not advance while in a
  // transaction. This effectively freezes time. Keep transactions short.
  optional bool begin = 1;
}

message TransactionResponse {
  enum Status {
    OK = 0;
    NO_TRANSACTION = 1;
    ALREADY_IN_TRANSACTION = 2;
  }
  optional Status status = 1 [default = OK];
}

// Describes a range of lines.
message LineRange {
  // Only one of these fields should be set:
  // ---------------------------------------
  // Return just the current contents of the screen.
  optional bool screen_contents_only = 1;

  // Return the last `trailing lines` of the buffer, which could go back into
  // scrollback history.
  optional int32 trailing_lines = 2;

  optional WindowedCoordRange windowed_coord_range = 3;
}

// Describes a range of values.
message Range {
  optional int64 location = 1;
  optional int64 length = 2;
}

// Describes a range of cells.
// |..xxxxx|
// |xxxx...|
// In the example above, the range of x's is: {start: {x:2, y:0}, end: {x:4, y:1}}
// The end coordinate is the first cell *after* the end of the range described (so an empty range
// has start == end)
message CoordRange {
  optional Coord start = 1;
  optional Coord end = 2;
}

// Describes a cell's location.
message Coord {
  optional int32 x = 1;
  // y=0 describes the first line. When the scrollback buffer is full and history is lost, the first
  // lines become unavailable, but the numbering is stable (so the Nth line is always the Nth line,
  // even if it's not the Nth *visible* line).
  optional int64 y = 2;
}

// Describes the content of a line.
message LineContents {
  optional string text = 1;

  // Some cells do not contain one code point. Use this to map code points in
  // `text` to a screen position. If the line has no uninitialized cells at its end, then the
  // sum of `repeats` equals the width of the display.
  //
  // For example, consider a line of text that appears on your display like:
  //   xyz compañía
  //
  // The corresponding value of `text` would be:
  //   xyzcompan~i'a
  // Note: ~ and ' are combining marks, but are shown uncombined for illustrative purposes.
  //
  // Each code point in "xyz" as well as each of the non-accented letters in compañía takes one
  // cell.
  //
  // The blank following 'z' is an uninitialized cell that has no code points,
  // so the z and the c in `text` are adjacent. It's unusual for these to occur in the middle
  // of a line, but it is possible.
  //
  // The ñ is composed of the letter n and a combining tilde (U+0303) (indicated in our example
  // as ~), while í is composed of the letter i and a combining acute accent (U+0301) (indicated in
  // our example as ').
  //
  // To map code points in `text` to screen positions, `code_points_per_cell`
  // provides the number of code points in each cell. In our example you would
  // get:
  //
  //   num_code_points=1, repeats=3     // x, y, z
  //   num_code_points=0, repeats=1     // uninitialized cell
  //   num_code_points=1, repeats=5     // c, o, m, p, a
  //   num_code_points=2, repeats=2     // n + combining tilde, i + combining acute accent
  //   num_code_points=1, repeats=1     // a
  //
  // Lines usually end with a series of uninitialized cells. These are not included.
  //
  // Here is psuedocode to interpret code_points_per_cell:
  //
  //   text_index_to_screen_coord = {}
  //   screen_coord_to_text_index = {}
  //   text_index = 0
  //   screen_coord = 0
  //   for cpps in code_points_per_cell:
  //     repeat cpps.repeats times:
  //       text_index_to_screen_coord[text_index] = screen_coord
  //       screen_coord_to_text_index[screen_coord] = text_index
  //       text_index += cpps.num_code_points
  //       screen_coord += 1
  //
  // Cells with images are omitted.
  repeated CodePointsPerCell code_points_per_cell = 2;

  // How does this line end?
  enum Continuation {
    // This line is not wrapped.
    CONTINUATION_HARD_EOL = 1;

    // The next line is a continuation of this line.
    CONTINUATION_SOFT_EOL = 2;
  }
  optional Continuation continuation = 3 [default = CONTINUATION_HARD_EOL];
}

message CodePointsPerCell {
  // Number of code points per cell
  optional int32 num_code_points = 1 [default = 1];

  // Number of adjacent cells with this number of code points (always one or more).
  optional int32 repeats = 2;
}

message ListSessionsRequest {
}

message SendTextRequest {
  // See documentation on session IDs
  optional string session = 1;

  // The text to send. As usual for proto buffers, this should be UTF-8
  // encoded. It will be converted to the session's encoding before being sent.
  optional string text = 2;

  // If set, input will not be broadcast when broadcasting is on.
  optional bool suppress_broadcast = 3;
}

message SendTextResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
  }

  optional Status status = 1;
}

message Size {
  optional int32 width = 1;
  optional int32 height = 2;
}

message Point {
  optional int32 x = 1;
  optional int32 y = 2;
}

message Frame {
  optional Point origin = 1;
  optional Size size = 2;
}

message SessionSummary {
    optional string unique_identifier = 1;
    optional Frame frame = 2;  // will not be set for buried sessions
    optional Size grid_size = 3;  // will not be set for buried sessions
    optional string title = 4;
}

message SplitTreeNode {
  optional bool vertical = 1;  // Direction of split pane divider
  repeated SplitTreeLink links = 2;  // Links to children

  message SplitTreeLink {
    oneof child {
      SessionSummary session = 1;
      SplitTreeNode node = 2;
    }
  }
}

message ListSessionsResponse {
  message Window {
    repeated Tab tabs = 1;
    optional string window_id = 2;
    optional Frame frame = 3;
    optional int32 number = 4;
  }
  message Tab {
    optional SplitTreeNode root = 3;
    optional string tab_id = 2;
    optional string tmux_window_id = 4;
    optional string tmux_connection_id = 5;
  }
  repeated Window windows = 1;
  repeated SessionSummary buried_sessions = 2;
}

message CreateTabRequest {
  // Leave unset to use the default profile.
  optional string profile_name = 1;

  // Leave unset to create the tab in a new window.
  optional string window_id = 2;

  // Valid to set only if window_id is set. Gives the desired index of the new tab.
  optional uint32 tab_index = 3;

  // If not set, the profile's command will be used. Use custom_profile_properties instead.
  optional string command = 4 [deprecated=true];

  // Modifies the profile to customize its behavior just for this session.
  repeated ProfileProperty custom_profile_properties = 5;
}

message CreateTabResponse {
  enum Status {
    OK = 0;
    INVALID_PROFILE_NAME = 1;
    INVALID_WINDOW_ID = 2;
    // The tab is still created, just not with the desired index.
    INVALID_TAB_INDEX = 3;
    // A $$VAR$$ substitution was not provided by the user.
    MISSING_SUBSTITUTION = 4;
  }
  optional Status status = 1;
  optional string window_id = 2;
  optional int32 tab_id = 3;
  optional string session_id = 4;
}

message SplitPaneRequest {
  // See documentation on session IDs
  optional string session = 1;

  enum SplitDirection {
    VERTICAL = 0;
    HORIZONTAL = 1;
  }
  optional SplitDirection split_direction = 2;

  // If true, new session is above/left of the session being split. Otherwise, it goes below/right.
  optional bool before = 3 [default=false];

  // Leave unset to use the default profile.
  optional string profile_name = 4;

  // Modifies the profile to customize its behavior just for this session.
  repeated ProfileProperty custom_profile_properties = 5;
}

message SplitPaneResponse {
  enum Status {
    OK = 0;
    SESSION_NOT_FOUND = 1;
    INVALID_PROFILE_NAME = 2;
    // This can happen if the session to be split is too small. If splitting multiple sessions and
    // one or more cannot be split, the status will be set to CANNOT_SPLIT, even if some did succeed
    // (in which case there will be one or more session_id's).
    CANNOT_SPLIT = 3;
    // Couldn't decode JSON
    MALFORMED_CUSTOM_PROFILE_PROPERTY = 4;
  }
  optional Status status = 1;

  // TODO(gln): this will not be set for tmux integration because the split happens only if/when the
  // tmux server acts on the request.
  // See documentation on session IDs.
  // If more than one session was split, there will be multiple session_id's.
  repeated string session_id = 2;
}