Skip to content
eternego / docs

Chat

The conversation screen — where you talk to her and watch her think. It's the default screen and the only one that holds a live WebSocket. URL: /persona/{id}/chat.

Layout, top to bottom: a header (title, her status, quick links to Status and Settings), an organ strip (which senses she has), the conversation stream, and the composer at the bottom.

The header

  • Title — "Your conversation with {name}".
  • Status line — her current status: Awake, Hibernating, or Something's wrong.
  • Status / Settings buttons — jump to those screens.

The organ strip

A row of chips, one per organ slot: Mind, Imagination, Mouth, Eye, Ear, Teacher, Researcher. Each shows set (configured) or empty. Hover for a one-line description of what it does. Clicking any chip jumps to that organ's tab in Settings — an empty chip to add the organ, a set one to change it. Mind is always set — it's the one required organ.

The strip reflects the persona record from GET /api/personas; it has no endpoint of its own.

The conversation stream

Her messages render in serif on the left; yours in sans on the right. Markdown is rendered. Each bubble shows the speaker, a timestamp, and — for anything that came through a non-web channel — a "via telegram" / "via discord" tag.

On open, the screen loads history from GET /api/persona/{id}/conversation and renders it. New activity then streams in live over the per-persona WebSocket /ws/{persona_id}. The frames it renders:

Frame type Becomes Notes
chat_message one of her text bubbles Her spoken words.
chat_image her bubble with an inline image url points at GET .../media/{filename}; click to open full size, or download.
chat_audio her bubble with an audio player Newly-arrived audio from her auto-plays; historical audio (on reload) stays quiet until you press play. Only one audio plays at a time.

Cross-channel mirrors. When she acts on, or hears from, a channel other than the web (Telegram, Discord), the web socket never gets a chat_message for it — instead a richer signal arrives. The screen mirrors those into conversation bubbles so this view stays a complete record: Said/Spoke/Drew become her bubbles, Read/Heard become yours, each tagged with the channel name. (See WebSocket frames for the signal shapes.)

The activity feed. While she's mid-response, a live "thinking" bubble shows the stages firing this beat — recognize, decide, learn, reflect, tool calls. Stages that didn't need to run this beat are folded as "rest". When her message lands, that activity is snapshotted onto the message so you can expand it later and see what she did to produce those words. Pure background noise (heartbeats, health checks) is filtered out and never shown.

The composer

The input box at the bottom. A textarea plus three controls.

Control Action API call
Textarea + Enter Send a text message. (Shift+Enter inserts a newline.) POST /api/persona/{id}/read with { "message": "<text>" }
Send button Same as Enter. POST .../read
Stop button Appears in place of Send while she's responding and the textarea is empty. A soft interrupt. POST .../read with { "message": "Stop" }
Paperclip (attach) Pick a file — image, audio, PDF, or text. POST .../attach (multipart, field file)
Mic Record a voice note; click again to stop and send. POST .../hear (multipart, field audio)

A few behaviors worth knowing:

  • Send and Stop both go to /read — Stop simply sends the word Stop as a normal message, which she reads on her next beat. There is no hard kill of an in-flight beat from here; it's a polite interrupt. (The soft-interrupt window keeps the Stop button live for about 10 seconds after her last activity, then reverts to Send.)
  • Attach accepts image/*, audio/*, .pdf, .csv, .json, .txt, .md in the file picker. The backend routes by extension — images to her Eye, audio to her Ear, documents to her Researcher. A type with no matching capability is rejected by the endpoint with 415. The full accepted set is in Perception → Attach.
  • Mic records in the browser (WebM/Ogg/MP4 depending on support) and uploads to /hear. The mic button is disabled if she has no Ear — clicking it then jumps you to the Ear settings tab instead. The /hear endpoint and /attach both ingest audio; /hear is the path for "she heard me speak just now", /attach for "I sent her an audio file".
  • The composer shows a small tip when she's missing an Eye ("she can't see images yet — give her an Eye") or Ear, linking to the right settings tab.

Your typed/attached message echoes into the stream immediately and a "thinking" bubble lights up; her reply arrives over the socket.

When she's not awake

If her status is anything other than active, the composer is hidden and a card explains why, with a one-click way out:

Status Card Button
hibernate "She's hibernating." — long pause. Wake her up → POST .../update with { "status": "active" }
sick "Something went wrong." — her Mind couldn't respond last beat. See Status → the Status screen

The three statuses are defined in Vocabulary. (asleep isn't one — sleep is an action that runs her night ritual, then she's back to active.)