// 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.

module browser.context_hub.mojom;

import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/uuid.mojom";
import "url/mojom/url.mojom";

feature kAutoTabGroups {
  const string name = "AutoTabGroups";
  const bool default_state = false;
};

feature kAutoTodos {
  const string name = "AutoTodos";
  const bool default_state = false;
};

enum AutoTodoStatus {
  kActive,
  kCompleted,
  kDismissed,
};

enum AutoTodoGroup {
  kNoMatch,
  kNudgeToClose,
  kReadingList,
  kUnfinishedAction,
};

struct GmailReference {
  url.mojom.Url message_url;
  string subject;
};

struct PhotosReference {
  url.mojom.Url photos_url;
};

union SourceReference {
  GmailReference gmail;
  PhotosReference photos;
};

// Data for Gmail-based AutoTodos.
struct FirstPartyData {
  // Source URLs where the AutoTodo was generated from.
  array<SourceReference> source_references;
  // The URL to navigate to when the user clicks to start the item.
  url.mojom.Url actionable_url;
};

// Data for Browser tab-based AutoTodos.
struct ThirdPartyData {
  // Associated tab Session ID.
  int64 tab_id;
  // Timestamp when the associated tab was last active.
  mojo_base.mojom.Time last_active_timestamp;
  // The group that this Tab-Todo belongs to.
  AutoTodoGroup group_type;
};

union AutoTodoData {
  // Data for Gmail-based AutoTodos.
  FirstPartyData first_party;
  // Data for Browser tab-based AutoTodos.
  ThirdPartyData third_party;
};

// Represents an item in the Auto Todo list.
struct AutoTodoItem {
  string id;
  string title;
  string description;
  // Status of the item.
  AutoTodoStatus status;
  // Importance score between 0 and 1 for the item.
  float score;
  // Type-specific data for the item.
  AutoTodoData data;
};

enum EntryType {
  kTab,
  kTextSelection,
};

// Represents an entry stored in the memory bank.
// See chrome/browser/context_hub/memory_bank/memory_bank_entry.h for field
// descriptions.
struct MemoryBankEntry {
  int64 id;
  EntryType type;
  mojo_base.mojom.Time timestamp;
  url.mojom.Url url;
  string tab_title;
  string? selected_text;
  array<string> tags;
  string? note;
  string? collection;
};

struct TabInfo {
  int64 id;
  string title;
  url.mojom.Url url;
};

struct TabGroup {
  string label;
  array<TabInfo> tabs;
  // Unique identifier for the saved group managed by TabGroupSyncService,
  // present for confirmed saved groups only.
  mojo_base.mojom.Uuid? saved_guid;
};

enum ChatRole {
  kUser,
  kAssistant,
};

struct ChatMessage {
  ChatRole role;
  string content;
};

// Context provided to the WebUI dialog for previewing the item to be saved.
struct SaveToMemoryBankContext {
  // The URL of the page where the context originated.
  url.mojom.Url url;
  // The title of the tab where the context originated.
  string tab_title;
  // The text selected from the page by the user.
  string? selected_text;
  // Whether the item being saved is a text selection rather than a tab.
  bool is_text_selection;
};

// User-specified annotations when saving a context item to the memory bank.
struct MemoryBankEntryAnnotations {
  // The collection name the entry should belong to. Null if not assigned to
  // no collection.
  string? collection;
  // User-provided note for the entry. Null if no note is provided.
  string? note;
  // Tags associated with the entry for grouping. Null or empty if no tags
  // are assigned.
  array<string>? tags;
};

// Represents feedback on an Auto Todo item.
struct AutoTodoItemFeedback {
  // The ID of the Auto Todo item in question.
  string todo_id;
  // Whether the item was liked or disliked by the user. Used to gather quick
  // feedback from teamfood users in a lightweight way.
  bool liked;
};

// Interface for the browser process to push updates to the WebUI page.
// Implemented in the renderer process (the Context Hub WebUI).
interface Page {
  // Notifies the WebUI when the list of Auto Todos in the cache changes.
  [RuntimeFeature=kAutoTodos]
  OnAutoTodosChanged(array<AutoTodoItem> todos);

  // Notifies the WebUI when First Party Auto Todos generation state changes.
  [RuntimeFeature=kAutoTodos]
  OnFirstPartyAutoTodosGenerationStateChanged(bool is_generating);

  // Notifies the WebUI when Third Party Auto Todos generation state changes.
  [RuntimeFeature=kAutoTodos]
  OnThirdPartyAutoTodosGenerationStateChanged(bool is_generating);
};

// Factory used by the WebUI page (caller) to create a PageHandler in the
// browser process (callee) for the Context Hub page.
interface PageHandlerFactory {
  // Creates a PageHandler instance and binds it to the given receiver and page
  // remote.
  CreatePageHandler(
      pending_remote<Page> page, pending_receiver<PageHandler> handler);
};

// Provides access to context hub features.
// The WebUI page (caller) uses this to interact with the browser
// process (callee).
interface PageHandler {
  // Generates and saves 1P Auto Todos to the cache. Gated by kAutoTodos flag.
  [RuntimeFeature=kAutoTodos]
  GenerateFirstPartyAutoTodos() => (bool success);

  // Returns stored Auto Todos from the cache, differentiated by whether they
  // are first party or third party, along with the timestamps when they were
  // last generated.
  [RuntimeFeature=kAutoTodos]
  GetAutoTodos() => (array<AutoTodoItem> first_party_todos,
                     array<AutoTodoItem> third_party_todos,
                     mojo_base.mojom.Time last_first_party_generation_time,
                     mojo_base.mojom.Time last_third_party_generation_time);

  // Updates an existing Auto Todo item in the cache, returns true if
  // successful.
  [RuntimeFeature=kAutoTodos]
  UpdateAutoTodo(AutoTodoItem todo) => (bool success);

  // Generates Tab-based Todos and stores them in the cache. Gated by kAutoTodos flag.
  [RuntimeFeature=kAutoTodos]
  GenerateTabBasedTodos() => (bool success);

  // Stores or updates feedback on an Auto Todo item in the cache.
  [RuntimeFeature=kAutoTodos]
  SetTodoFeedback(AutoTodoItemFeedback feedback) => ();

  // Deletes feedback on an Auto Todo item by Todo item ID from the cache.
  [RuntimeFeature=kAutoTodos]
  DeleteTodoFeedback(string id) => ();

  // Clears all todo feedback items from the cache.
  [RuntimeFeature=kAutoTodos]
  ClearTodoFeedbacks() => ();

  // Returns all cached todo feedback items from the cache.
  [RuntimeFeature=kAutoTodos]
  GetTodoFeedbacks() => (array<AutoTodoItemFeedback> feedbacks);

  // Returns initial context details for saving to memory bank.
  GetSaveToMemoryBankContext() => (SaveToMemoryBankContext? context);

  // Returns all entries currently stored in the memory bank.
  GetAllMemoryBankEntries() => (array<MemoryBankEntry> entries);

  // Deletes entries from the memory bank.
  DeleteMemoryBankEntries(array<int64> ids) => ();

  // Saves the current context entry to the memory bank with user annotations.
  SaveMemoryBankEntry(MemoryBankEntryAnnotations annotations) => (bool success);

  // Returns all unique tags stored in the memory bank.
  GetAllMemoryBankTags() => (array<string> tags);

  // Returns all unique collections stored in the memory bank.
  GetAllMemoryBankCollections() => (array<string> collections);

  // Returns the list of open ungrouped tabs in the current window.
  [RuntimeFeature=kAutoTabGroups]
  GetTabs() => (array<TabInfo> tabs);

  // Retrieves and groups related open tabs based on the user command.
  // User command is inputted via WebUI textbox.
  [RuntimeFeature=kAutoTabGroups]
  RetrieveAndGroupTabs(string user_command) => (array<TabGroup> groups,
                                                array<TabInfo> ungrouped_tabs,
                                                ChatMessage? llm_response);

  // Returns stored tab groups and chat history from the cache along with
  // ungrouped tabs. Used on page start up.
  [RuntimeFeature=kAutoTabGroups]
  GetExistingTabGroupsAndChats() => (array<TabGroup> groups,
                                     array<TabInfo> ungrouped_tabs,
                                     array<ChatMessage> history);

  // Switches to the specified tab.
  SwitchToTab(int64 tab_id);

  // Closes the specified tab.
  CloseTab(int64 tab_id);

  // Clears stored tab groups.
  [RuntimeFeature=kAutoTabGroups]
  ClearTabGroups() => ();

  // Clears stored tab group chat history.
  [RuntimeFeature=kAutoTabGroups]
  ClearTabGroupChatHistory() => ();

  // Sends a request to Gemini with the user command and selected memory bank
  // entry IDs.
  AskGeminiWithContext(
      string user_command, array<int64> memory_bank_entry_ids)
      => (ChatMessage response);

  // Confirms all suggested tab groups to the browser window and saves them
  // to TabGroupSyncService.
  [RuntimeFeature=kAutoTabGroups]
  ConfirmAllTabGroups() => (bool success);

  // Returns list of confirmed tab groups currently open or saved.
  [RuntimeFeature=kAutoTabGroups]
  GetConfirmedTabGroups() => (array<TabGroup> groups);

  // Removes a confirmed tab group from TabGroupSyncService and ungroups its
  // open tabs in the browser window without closing them.
  [RuntimeFeature=kAutoTabGroups]
  RemoveConfirmedTabGroup(mojo_base.mojom.Uuid saved_guid) => ();

  // Closes an open confirmed tab group from the browser window without removing
  // its saved state from TabGroupSyncService.
  [RuntimeFeature=kAutoTabGroups]
  CloseConfirmedTabGroup(mojo_base.mojom.Uuid saved_guid) => ();

  // Removes all confirmed tab groups from TabGroupSyncService and ungroups
  // their open tabs in the browser window.
  [RuntimeFeature=kAutoTabGroups]
  RemoveAllConfirmedTabGroups() => ();
};