Add include/hyperkitty.hrl

include/hyperkitty.hrl

@@ -0,0 +1,121 @@
+%%%-------------------------------------------------------------------
+%%% HyperKitty Chromium :: shared entity schemas (data_model).
+%%%
+%%% These records are the canonical in-memory shape of every entity
+%%% named in the specification's <data_model>. Each has a matching
+%%% `to_map/1' clause in hk_schema.erl for JSON transport. Records
+%%% (not maps) are used for these because entity shape is meant to
+%%% be closed and compiler-checked at the points that construct
+%%% them (agent runtime, browser controller, search harness); the
+%%% *wire* representation is a map/JSON, produced only at the
+%%% boundary, in hk_schema.
+%%% -------------------------------------------------------------------
+
+%% ---- Agent ---------------------------------------------------------
+%% Mirrors HK-AGENT's <agent_state> enumeration exactly.
+-record(agent, {
+    agent_id            :: binary(),
+    objective            :: #{} | undefined,      % #agent_objective{}
+    state                :: created | ready | planning | executing
+                           | waiting | completed | failed | terminated,
+    capabilities         :: [atom()],              % explicitly granted tool names
+    action_count = 0     :: non_neg_integer(),
+    started_at_ms        :: integer(),
+    updated_at_ms        :: integer(),
+    limits               :: map(),                 % see hk_agent_fsm limits map
+    result                :: term() | undefined,
+    failure_reason        :: term() | undefined
+}).
+
+-record(agent_objective, {
+    objective_id  :: binary(),
+    agent_id      :: binary(),
+    description   :: binary(),        % what the agent was asked to do
+    success_criteria :: binary() | undefined,
+    created_at_ms :: integer()
+}).
+
+%% ---- Browser --------------------------------------------------------
+-record(browser_session, {
+    session_id     :: binary(),
+    owner_agent_id :: binary() | undefined,   % undefined = system/manual session
+    profile        :: binary(),               % profile name, isolates cookies/storage
+    pid            :: pid() | undefined,
+    status         :: starting | ready | busy | closing | closed | crashed,
+    tabs           :: [binary()],              % tab_ids
+    created_at_ms  :: integer(),
+    updated_at_ms  :: integer()
+}).
+
+-record(browser_tab, {
+    tab_id        :: binary(),
+    session_id    :: binary(),
+    url           :: binary() | undefined,
+    title         :: binary() | undefined,
+    status        :: opening | loading | idle | closed,
+    created_at_ms :: integer(),
+    updated_at_ms :: integer()
+}).
+
+%% ---- Search -----------------------------------------------------------
+-record(search_job, {
+    job_id         :: binary(),
+    owner_agent_id :: binary() | undefined,
+    query          :: binary(),
+    stage          :: user_query | query_normalization | search_planner
+                     | search_provider | result_normalization | url_deduplication
+                     | content_retrieval | content_extraction | source_ranking
+                     | result_synthesis | frontend_visibility | done | failed,
+    max_iterations :: pos_integer(),
+    iteration      :: non_neg_integer(),
+    results        :: [binary()],   % result_ids
+    created_at_ms  :: integer(),
+    updated_at_ms  :: integer()
+}).
+
+-record(search_result, {
+    result_id     :: binary(),
+    job_id        :: binary(),
+    url           :: binary(),
+    normalized_url:: binary(),
+    title         :: binary() | undefined,
+    snippet       :: binary() | undefined,
+    rank          :: number() | undefined,
+    source_document_id :: binary() | undefined,
+    created_at_ms :: integer()
+}).
+
+-record(source_document, {
+    document_id    :: binary(),
+    url            :: binary(),
+    fetched_at_ms  :: integer(),
+    content_type   :: binary() | undefined,
+    extracted_text :: binary() | undefined,
+    citation_map   :: map()   % passage/anchor -> location within extracted_text
+}).
+
+%% ---- Messaging --------------------------------------------------------
+-record(message, {
+    message_id      :: binary(),
+    sender          :: binary(),
+    recipient       :: binary(),
+    timestamp       :: integer(),
+    conversation_id :: binary(),
+    message_type    :: user_to_agent | agent_to_user | agent_to_agent | system,
+    payload         :: map(),
+    status          :: queued | delivered | read | failed
+}).
+
+%% ---- Operation ----------------------------------------------------------
+%% Every mutating API call returns an #operation{}; see api spec
+%% ("Every mutating operation should return an operation identifier").
+-record(operation, {
+    operation_id  :: binary(),
+    request_id    :: binary(),
+    kind          :: atom(),      % e.g. agent_create, browser_navigate, search_start
+    status        :: accepted | in_progress | succeeded | failed,
+    subject       :: {atom(), binary()} | undefined,
+    error         :: map() | undefined,
+    created_at_ms :: integer(),
+    updated_at_ms :: integer()
+}).