# Agent App: Hermes Chat (and My Assistant on the web)

## What it does

A salesperson chats with their own Hermes assistant from the Sales Agent app, as an
alternative to Telegram. The assistant runs on the **Hermes lab box**, a separate GCP
VM (`hermes-lab` in project `wk-property`) running Nous Research's Hermes Agent with
one profile per person. PETA does not run the assistant. It relays each message to
the box, waits for the reply, stores both for the app, and pushes the reply to the
salesperson's phone.

- **Who sees it:** every staff member who can sign in to the app, on a server
  whose `.env` names a box. They set up their own assistant with one tap ("Set up
  my assistant"; Lee Jie, 2026-10-23: salespeople do it themselves). A super
  admin can switch anyone's off on Setting → Hermes Assistants. `HERMES_SELF_SERVE=false`
  turns self-setup off, so only people a super admin maps see it.
- **Messages:** typed messages and voice notes. A voice note is transcribed here,
  because Hermes's API takes text and images only. The assistant's scheduled jobs
  (the morning brief, the nightly chat capture, the nightly Link/Organise/Signal, a
  knowledge owner's weekly check) post their messages into the same chat, since
  salespeople do not use Telegram.
- **Morning brief, goals and WhatsApp (box jobs, 2026-11-02):** these run on the box and
  need nothing new in PETA:
  - **Morning brief:** one message every morning in the person's chat, at 08:30 unless they
    change it ("Send me my morning brief every morning at 7:45.", "Stop my morning brief.").
    It leads with today's one thing and a ready draft. Then come their numbers, counted in PETA
    with their own permissions: buyers waiting on a WhatsApp reply, WhatsApp messages sent,
    follow-ups due, new leads and bookings. Someone who sees more than their own leads also gets
    the same numbers per colleague.
  - **"Set my goals."** is a five-minute version of the chief-of-staff interview. It writes
    `GOALS.md`, and the brief counts against it.
  - **Nightly WhatsApp capture** (about 01:00): reads yesterday's WhatsApp with the person's
    leads from PETA and keeps each conversation that matters as a note in their brain. The
    nightly loop and the next brief use those notes.
  - **"Plan my webinar for <area>."** uses the course's Webinar Architect, with PETA's past
    webinar numbers.
  - The jobs read PETA through `lab_peta.py`, on the same signed endpoint as the assistant's
    tools; see [Data access](/docs/modules_handbook/agent-app/hermes-chat/data-access.md).
  - "Waiting on a reply" uses PETA's own `ReplyOwed` rule and tiers, the red marks on the Leads
    list.
  - **Quiet hours** (asked in "Ask me what goes in my morning brief."): during them the box holds
    every other job message. The first morning-brief check after the quiet hours end sends them
    together.
  - **Never edit an `AGENTS.md` from the chat.** Hermes protects those files, and the approval it
    asks for cannot be given in the app, so the whole reply fails as "needs an approval the app
    cannot give". The person's own rules live in `_System/chief-of-staff/WORKING-RULES.md`. That
    covers the interview, "Add a rule" and Link rules.
  - **A reply has `hermes.reply_timeout_minutes` (15).** A long job, like a full webinar script,
    is split across replies by its skill.
- **Brain search, GBrain (box, 2026-11-03):** each assistant can search its own person's notes by
  keyword and by meaning, and names the note it used. Example: "What did lead 1234 say about the
  loan?"
  - The notes are their own captures and notes plus the company and department notes. They come
    from a nightly index in that person's own Postgres database on the box. Embeddings are Voyage
    voyage-4.
  - The tools are read-only, and nobody's index holds anyone else's notes.
  - PETA isn't involved: live PETA data still comes from the data tools.
  - Setup and limits are in the box runbook, `_System/runbook.md`.
- **Weekly company digest:** every Monday morning the box sends a summary of what
  came up for two or more salespeople the week before to each knowledge owner (Wai
  Kit) as a message in their assistant chat, and to anyone who ticked "Hermes lab —
  weekly company digest" on Setting → Notifications (event `hermes.weekly_digest`).

- **Files (2026-10-31, Wai Kit: "ctrl v can paste anything"):** any type, up to
  500 MB each, 20 per message, on the web (paperclip, drop, or Ctrl+V into the box)
  and in the app (photos and videos, the camera, or Files). Each file uploads in
  pieces as soon as it is added (`ChunkedUploadService`, so not bound by Cloudflare's
  100 MB), and the message is sent with their uuids. Before the run, the box
  downloads each one from a 30-minute signed link into the person's own folder,
  `staff/<profile>/08. Sources/attachments/` (kept out of the brain's nightly git
  commit). The run's text lists each file's name, type, size and path, and the
  assistant opens it with its own tools. Pictures (JPEG, PNG, GIF, WebP up to 3.5 MB,
  five per message) are also sent as image parts of the run's input, so the
  assistant sees them directly. Both paths were verified on the box 2026-10-31:
  a picture sent inline was read correctly, and so were a text file and a picture
  opened from the folder. The box side is `POST /lab-admin/people/<profile>/attachments`
  in `admin_api.py`, handled by `/usr/local/lib/hermes-lab/lab_attachments.py`.
- **Reading PETA's data:** the assistant queries live PETA data with the PETA permissions of
  the person it belongs to: their tables, and only their leads' rows when they see only some
  leads. See [Data access](/docs/modules_handbook/agent-app/hermes-chat/data-access.md).

- **Idea Briefs (2026-11-04):** a separate `idea-bot` profile on the box writes a daily video idea, approved on
  My Assistant → Idea Briefs. See [Idea Briefs](/docs/modules_handbook/agent-app/hermes-chat/idea-briefs.md).

The wire contract for the app is the *Hermes assistant chat* section of the
[Agent API doc](/docs/agent-app/PROPERTYLAB-SALES-AGENT-API.md).

**Nav:** Setting → Hermes Assistants (super admins). The chat itself is in the app's
Messages tab, and on the web at **My Assistant → Chat** (`/manage/assistant`): the Chat main tab of the
Operations **My Assistant** hub (`MyAssistantTabs`, beside My Workspace and Revenue
Intelligence since 2026-10-31), shown only to someone the app offers it to. Someone with no
lead level but an assistant gets a My Assistant entry that lands straight on the Chat.

## How it works

**The box side.** Each salesperson is a Hermes profile on the box. Hermes's API
answers at `https://<box>/p/<profile>/v1/...` and accepts a request only with that
profile's own key. Both sides work out the key from one shared secret:
`HMAC-SHA256("hermes-lab-api:<profile>", HERMES_LAB_SECRET)`. PETA holds the secret in
`.env`. The box holds the same value (`sudo hermes-lab set-api-secret`) and writes
each profile's key when it makes it, so no per-person key is ever copied. The box's
firewall lets only PETA production and the office reach port 443. The box's own
runbook is `/srv/propertylab-brain/_System/runbook.md`.

**The box's admin API** (`https://<box>/lab-admin/`, `HermesLabAdmin`) is how PETA
sets people up and changes them without anyone running a command on the box:
`GET people` (everyone, their department and what they own), `POST people` (set
someone up), `PUT people/<profile>` (department, owned areas) and `DELETE
people/<profile>` (archive). Each call is signed with the same secret: HMAC-SHA256
over `hermes-lab-admin`, the method, the path, a unix time and the exact body, in
`X-Lab-Time` and `X-Lab-Signature`. The box refuses one older than five minutes, or
the same one twice.

**Setting up.** `POST hermes/setup` makes a `hermes_assistants` row with no profile
and `STATUS_SETTING_UP`, and queues `SetUpHermesAssistant` (AI lane: the box may
take up to `hermes.admin_timeout`, 240s). The box picks the profile name from the
person's name (`example-name-test`, `-2` for a second person of that name), keyed on
the PETA user's uuid, so a retry returns the same profile. The job stores it, sets
`STATUS_READY` and posts a welcome message with a push. Two failed tries leave
`STATUS_SETUP_FAILED` with a plain-words `error`; tapping again retries. The box
serves a new profile without a gateway restart, and only answers once Hermes does.

**Notices from the box.** `POST /webhooks/hermes-lab/notices`
(`HermesLabNoticesController`), signed by the box with `hermes-lab-notice`
(`HermesLabNoticeRequest` checks it against the raw body):
- `job`: a scheduled job's message for someone with no Telegram. It is stored as an
  assistant message that answers nothing (`HermesMessageRepository::notice()`,
  idempotent on the box's notice id) and pushed. 404 when no ready, switched-on
  assistant has that profile; the box keeps the message in the job's own output.
- `weekly_digest`: sent through `Notifier` as `hermes.weekly_digest`.
The box needs PETA's URL once: `sudo hermes-lab set-peta-url https://<this server>`.

**Mapping.** `hermes_assistants` holds one row per salesperson: `user_id` → `profile`,
plus `status`, `error`, `session_id` and `is_active`.
- `session_id` names the CURRENT general chat (see *Chats and bots* below). A new
  one is made on create, on a profile change, and on a new general chat.
- Three gates on `HermesAssistant`: `offeredTo($user)` decides whether the app shows
  the Assistant at all (the `hermes` entry in `agent-channels`, `GET hermes` and
  `setup`); `reachableFor($user)` is the switched-on row in any setup state;
  `activeFor($user)` is a ready one, the gate for sending and for pushes.

**A message's journey.** It is all queued, so no worker waits while the assistant
thinks:
1. `POST hermes/messages` stores the message as QUEUED. The app's `request_uuid` is
   its uuid, which makes the send idempotent. The assistant row is locked while
   this happens, so a second message is refused (409) while one is pending.
2. `StartHermesRun` calls `POST /p/<profile>/v1/runs` with `input`, the
   message's chat `session_id`, the chat's bot `instructions` when it has a bot,
   and `Idempotency-Key` set to the message uuid. A
   retried job gets the same run back, never a second one. The message becomes
   RUNNING with the `run_id`. If the box answers 401, 403 or 404 (no such profile,
   or it refused the key), the message fails at once as "not set up on the lab
   box", since a retry cannot fix that. Any other error is retried 3 times before
   "Could not reach your assistant".
3. `PollHermesRun` checks `GET /v1/runs/{id}` every `hermes.poll_seconds` by
   re-dispatching itself:
   - `completed` → the reply row is written and the message becomes DONE.
   - `failed`, `cancelled` or `interrupted` → FAILED with a plain-words `error`.
   - `waiting_for_approval` → stopped and FAILED. The app cannot give approvals;
     Telegram can.
   - A run the box no longer knows (it restarted) → FAILED.
   - Longer than `hermes.reply_timeout_minutes` (15) → stopped and FAILED.
4. `SendHermesChatPush` notifies that salesperson's own installations (kind
   `hermes_reply` in `agent_app_push_deliveries`, once per message and device). It
   fires for a reply and for a failure.
   - **The phone shows it only once the person has allowed alerts.** A "sent" row
     here does not prove a banner. Up to 1.0.93 (99) the app asked only when someone
     tapped Turn on (Settings → Message alerts, or the Messages card). So an
     iPhone that never tapped showed nothing, the morning brief included, and the
     app was missing from the phone's notification settings. Lee Jie hit this on
     2026-11-03. The Check permissions & network tick also passed on every
     iPhone, because that check only runs on Android.
   - **From the next app build** the app asks once the shell is on screen after
     sign-in, the tick reads the real iOS permission, and the alerts copy names
     the assistant. Assistant alerts show the start of the reply. Only customer
     alerts hide the message.

Hermes keeps the conversation itself: a run with the same `session_id` loads that
session's history. The `hermes_messages` rows exist so the app can show and page the
thread.

**Chats and bots (2026-10-28).** Lee Jie asked for chats like Grok's bots: many
chats per person, general ones and ones with a bot, and many chats per bot.
- **A chat is one Hermes session.** `hermes_chats` stores `session_id`, `title`
  (taken from the first message sent in it), `last_message_at`, and an optional
  `hermes_bot_id`. Every `hermes_messages` row has a `hermes_chat_id`. The
  migration split the existing messages into one chat per session they were in,
  which is what "New chat" used to start.
- **A bot is the same assistant with instructions.** `hermes_bots` belongs to the
  person (`user_id`), so the bots survive a re-mapping. `HermesBot::runInstructions()`
  goes to the Runs API as `instructions`. Hermes adds that text after the profile's
  own system prompt for that run only and keeps no copy, so it is sent with every
  run of the chat. A bot therefore shares the person's notes, memory and knowledge,
  and needs nothing on the box. Separate memory per bot would need a Hermes profile
  per bot. Deleting a bot deletes its chats; editing it applies from the next message.
- **The current general chat.** `hermes_assistants.session_id` names it. It is where
  the box's job messages land (`notice()`), and it is what a request that names no
  chat uses, so an app that predates chats keeps working with nothing changed. A new
  general chat becomes the current one. Removing the current chat starts a fresh one.
  The current chat's row is made on its first message or notice, never by viewing it.
- **One message at a time, across all chats.** The chats share one profile, so the
  409 for a pending reply applies to every chat. The thread view reports `busy` and
  `busy_chat_uuid`.
- **The reply push** carries `chat_uuid`, so a tap can open the right chat.
- **API.** `GET hermes?chat=`, plus `chat` on `messages` and `voice`, for the
  thread. Chats: `GET`/`POST hermes/chats` (`bot` optional) and `DELETE
  hermes/chats/{uuid}`. Bots: `GET`/`POST hermes/bots`, `PUT`/`DELETE
  hermes/bots/{uuid}`. My Assistant has the same through `manage.assistant.*`,
  with `?chat=` on the page.
- **Not yet confirmed:** whether the box's Claude provider
  (`claude-subscription-directsdk-experimental`) honours `instructions`. Hermes
  v0.22.2 passes it on as `ephemeral_system_prompt` (`api_server_runs.py`). One run
  with a bot on the box settles it.

**Voice notes.** `POST hermes/voice` takes the app's raw PCM, the same format as a
WhatsApp voice note. The steps:
1. `AgentVoiceEncoder` converts it to OGG/Opus. That needs `agent_app.voice_notes_enabled`
   and ffmpeg: a bare name found on the PATH, or a full path in
   `AGENT_APP_VOICE_FFMPEG_BINARY` (needed under php-fpm, whose PATH is short).
2. It is stored through `MediaService` (collection `hermes_voice`), then the message
   row is written as TRANSCRIBING.
3. `TranscribeHermesVoice` runs on the transcription lane, using
   `TranscriptionService` with Gemini first and Deepgram as fallback, without
   speaker labels (one person is talking). It writes the transcript as the body
   and hands the message on as QUEUED.

`supports_voice` in the thread response tells the app whether to offer the microphone.
`voice_url` is a 30-minute signed link to the OGG. It is null when the disk cannot
sign one (a local disk in development), and the app then shows the note without a
player rather than the thread failing.

**Reporting a reply.** Google Play asks apps with AI-generated content to let users
flag it without leaving the app. In the app, each assistant reply has a flag button:
`POST hermes/messages/{uuid}/report` with an optional reason stamps `reported_at` and
`report_reason` on that reply (`HermesMessageRepository::report()`), and the first
report sends `hermes.reply_reported` through the Notifier with the reply, who reported
it and why. Reporting again changes nothing. The thread marks it `reported`. Nothing
goes back to the box: an admin reads the alert and fixes the assistant's notes or
skills by hand.

**AI notice in the app.** Before setup or the first message on a phone, the app shows
what is sent where (Anthropic's Claude on the box, Gemini or Deepgram for voice
notes) and waits for Agree and continue, kept per account on that phone. Apple asks
for this before personal data goes to a third-party AI. The web has no such notice.

**Setting page.** Lists every assistant, with its department and what it owns
read live from the box (`GET people`; the page still loads, without them, when the
box does not answer). Super admins:
- **Edit:** the department (which knowledge and skills the assistant gets) and
  **Knowledge owner of** (company, a department). Only changed values are sent, to
  the box first; a refusal changes nothing here. One owner per area: ticking an area
  takes it from its current owner. Also switch an assistant on or off.
- **Remove:** deletes the app's copy of the chat and its voice notes. With "Also
  archive their assistant on the lab box" (on by default unless they also use
  Telegram), the box archives their profile and notes too, and their access there ends.
- **Add assistant:** only for someone already linked on Telegram (`sudo hermes-lab
  link` printed their profile name).
- **Test** calls the box's `GET /p/<profile>/v1/models` with the derived key. A 404
  means the box has no profile by that name; a 401 means the profile exists but
  refused the key, so the two secrets differ.

**My Assistant (web).** `Manage\AssistantController` renders
`Pages/Manage/Assistant/Index.vue` with the same thread as the app: the rules both share
(what is shown, setup, sending, new chat) live in the controller concern
`ServesHermesChat`, used by `AgentHermesController` too. The page re-reads only the
`chat` prop every 3 seconds while a reply is pending or setup runs, every 20 seconds
otherwise, and "Load older messages" fetches the optional `older` prop. A send keeps its
`request_uuid` until the chat shows it, like the app. The sidebar entry reads the shared
`auth.user.hermes_assistant` (`HermesAssistant::offeredTo`).

**Setup on a server.**
1. Set `HERMES_LAB_URL` (e.g. `https://hermes-lab.propertylab.com.my`) and
   `HERMES_LAB_SECRET` in `.env`. Use the same secret the box holds, and never
   commit it.
2. Run the migration, and restart Horizon so it reads `config/hermes.php`.
3. The box's firewall must allow this server's IP on 443.
4. On the box, once: `sudo hermes-lab set-peta-url https://<this server>`, so job
   messages and the Monday digest reach this server. Only one PETA receives them.
5. On Setting → Notifications, whoever wants the Monday digest ticks "Hermes lab —
   weekly company digest".

**Known gaps.**
- Files the assistant makes (a `MEDIA:` path in its reply) are not delivered to the
  app.
- Approvals cannot be given from the app.
- The app's chat and the person's Telegram chat are separate Hermes sessions. They
  share the assistant's notes and memory, but not the transcript.
- A job's message is not part of the assistant's session: replying "what do you
  mean?" to it reaches an assistant that has not seen it (it can read the notes the
  job wrote).
- No Hermes Desktop for salespeople: it gives whoever signs in every profile's
  chats, settings and keys. My Assistant is the laptop way in.
- My Assistant sends text and files, not voice notes: those are sent from the app
  (the web shows their transcript and a player). No push on the web; the page
  re-reads the chat itself.
- A picture is in the conversation for the turn it was sent; later turns see only
  its path (Hermes flattens earlier turns to text), so the assistant reopens the file
  from the folder when asked about it again.
- An uploaded file that is never sent stays in storage (no sweep yet).
- Reporting a reply and the AI notice are app only.

## Related files

**Backend**
- `src/Hermes/HermesAssistant.php`: the mapping, and `activeFor()`
- `src/Hermes/HermesMessage.php`: roles, types and statuses
- `src/Hermes/HermesChat.php`, `src/Hermes/HermesBot.php`: chats and the person's own bots
- `src/Hermes/HermesMessageAttachment.php`: files sent with a message, their limits, and `runInput()` (the text the run sends)
- `app/Jobs/Hermes/DeliverHermesAttachments.php`: one file per job to the box, then the run
- `app/Http/Transformers/AgentApi/HermesAttachmentTransformer.php`
- `resources/js/composables/useChatAttachments.js`, `resources/js/Pages/Manage/Assistant/Partials/AttachmentTray.vue`, `MessageAttachments.vue`: the web composer's files
- `src/Hermes/Repositories/HermesChatRepository.php`, `src/Hermes/Repositories/HermesBotRepository.php`
- `src/Hermes/Repositories/HermesAssistantRepository.php`
- `src/Hermes/Repositories/HermesMessageRepository.php`: idempotent `create()`, plus `transcribed()`, `start()`, `reply()`, `fail()` and `report()`
- `src/Hermes/Services/HermesClient.php`: key derivation and the Runs API calls
- `src/Hermes/Services/HermesDataService.php`, `src/Hermes/Support/HermesDataTables.php`: the assistant reading PETA ([Data access](/docs/modules_handbook/agent-app/hermes-chat/data-access.md))
- `app/Jobs/Hermes/StartHermesRun.php`
- `app/Jobs/Hermes/PollHermesRun.php`
- `app/Jobs/Hermes/TranscribeHermesVoice.php`
- `app/Jobs/Hermes/SetUpHermesAssistant.php`
- `src/Hermes/Services/HermesLabAdmin.php`: the box's admin API, and the signature both directions use
- `app/Http/Controllers/Webhooks/HermesLabNoticesController.php`, `app/Http/Requests/Webhooks/HermesLabNoticeRequest.php`
- `config/notify.php`: the `hermes.weekly_digest` and `hermes.reply_reported` events
- `app/Jobs/AgentApp/SendHermesChatPush.php`
- `src/AgentApp/Services/FirebaseCloudMessaging.php` (`sendHermesReply()`), and `src/AgentApp/AgentAppPushDelivery.php` (`KIND_HERMES_REPLY`)
- `src/AgentApp/Support/AgentChannels.php`: the `hermes` platform
- `app/Http/Controllers/AgentApi/AgentHermesController.php`
- `app/Http/Controllers/Concerns/ServesHermesChat.php`: the rules the app and the web share
- `app/Http/Controllers/Manage/AssistantController.php`, `app/Http/Requests/Manage/Assistant/`
- `app/Http/Requests/AgentApi/ShowAgentHermesRequest.php`
- `app/Http/Requests/AgentApi/SendAgentHermesMessageRequest.php`
- `app/Http/Requests/AgentApi/SendAgentHermesVoiceRequest.php`
- `app/Http/Requests/AgentApi/ReportAgentHermesMessageRequest.php`
- `app/Http/Transformers/AgentApi/HermesMessageTransformer.php`, `HermesChatTransformer.php`, `HermesBotTransformer.php`
- `app/Http/Requests/AgentApi/StoreAgentHermesChatRequest.php`, `SaveAgentHermesBotRequest.php`
- `app/Http/Controllers/Manage/Settings/HermesAssistantsController.php`
- `app/Http/Requests/Manage/Settings/HermesAssistants/`: `StoreRequest`, `UpdateRequest` and `HermesAssistantQueryRequest`
- `config/hermes.php`

**Frontend**
- `resources/js/Pages/Manage/Settings/HermesAssistants.vue`
- `resources/js/Pages/Manage/Assistant/Index.vue`: My Assistant, with `Partials/ChatList.vue` (chats and bots), `Partials/BotForm.vue` and `Partials/BotFormModal.vue`
- `resources/js/Layouts/ManageLayout.vue`: the My Assistant sidebar entry (`myAssistantNav`)
- `resources/js/Components/MyAssistantTabs.vue`: the hub strip; the Chat main tab is gated on `auth.user.hermes_assistant`
- `resources/js/Components/SettingTabs.vue`: the `hermes-assistants` tab

**Partners app** (the `propertylab-b2b-app` repo)
- `lib/features/hermes/`: `HermesApi`, `HermesChatViewModel`, `HermesChatPage`, `HermesChatsPage` (chats and bots), `HermesBotPage` (a bot's name and instructions), `HermesAssistantDisclosure` (the AI notice; `currentMaterialVersion` `2026-10-28-v2-peta-records` asks everyone again now that it can read PETA records), and the Assistant row on the Messages tab
- `lib/features/notifications/application/whatsapp_notification_router.dart`: a tapped reply alert keeps its `chat_uuid` (`takePendingAssistantChat()`), so the chat it is in opens
- `lib/ui/privacy_page.dart`: `assistantProcessingNotice` and the Privacy & data page's "Your assistant" section
- `integration_test/hermes_chat_acceptance_test.dart`: sign in, open the chat, send, wait for the reply (opt-in, against a local or staging server)

**Migrations**
- `database/migrations/2026_10_20_220000_create_hermes_assistants_and_messages.php`
- `database/migrations/2026_10_26_120000_add_report_columns_to_hermes_messages_table.php`
- `database/migrations/2026_10_28_120000_create_hermes_bots_and_chats.php`: also splits existing messages into chats

**Routes**
- `routes/agent-api.php`: `hermes`, `hermes/setup`, `hermes/messages`, `hermes/messages/{id}/report`, `hermes/voice`, `hermes/new-chat`, `hermes/chats` and `hermes/bots`
- `routes/main.php`: `webhooks.hermes-lab.notices`
- `routes/web.php`: `manage.settings.hermes-assistants.*`, `manage.assistant.*`

**Tests**
- `tests/Feature/AgentApi/AgentHermesChatTest.php`
- `tests/Feature/AgentApi/HermesAssistantsSettingsTest.php`
- `tests/Feature/Manage/AssistantPageTest.php`
