Working directory: ~/Projects/homestead
Author: ~nocsyx-lassul
Date: 2026-01-24
Status: Draft
A two-part presence system for Tlon that provides both ephemeral status indicators (typing, viewing, in-call) and persistent availability states (online, away, offline). Designed to feel alive while respecting user privacy through opt-out controls.
- Show when someone is typing in a chat
- Indicate who's currently viewing a channel
- Display call/listening status
- Show online/away/offline availability
- Track last-seen timestamps
- Allow users to opt-out (go unseen) at any level
Two complementary systems with distinct purposes:
┌─────────────────────────────────────────────────────────────────────┐
│ PRESENCE SYSTEM │
├─────────────────────────────────┬───────────────────────────────────┤
│ EPHEMERAL (seconds) │ AVAILABILITY (hours) │
├─────────────────────────────────┼───────────────────────────────────┤
│ %presence agent (NEW) │ %contacts agent (EXISTING) │
│ • typing indicators │ • online/away/offline │
│ • viewing status │ • last-seen timestamp │
│ • call/listening │ • custom status message │
│ • local storage only │ • profile field sync │
│ • routed via %chat/%groups │ • direct profile queries │
│ • auto-timeout (seconds) │ • user-controlled updates │
└─────────────────────────────────┴───────────────────────────────────┘
Handle short-lived, context-specific presence like typing indicators. Local-only storage with network routing delegated to %chat and %groups.
%presence only accepts self-pokes. It never talks to the network directly.
┌──────────────────────────────────────────────────────────────────────┐
│ Network Flow: Typing Indicator │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ [Their Ship] [My Ship] │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ %chat │ ──── network ──→ │ %chat │ │
│ │ (sends) │ │ (validates)│ │
│ └─────────────┘ └──────┬──────┘ │
│ │ │
│ │ local poke │
│ ↓ │
│ ┌─────────────┐ │
│ │ %presence │ │
│ │ (stores) │ │
│ └──────┬──────┘ │
│ │ │
│ │ subscription update │
│ ↓ │
│ ┌─────────────┐ │
│ │ UI/Client │ │
│ │ (displays) │ │
│ └─────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
+$ topic @tas :: typing, viewing, call, listening
+$ context path :: where (e.g. /chat/~zod/general, /call/~zod/room-1)
+$ status [=topic =context expires=@da] :: topic + context + expiry
+$ presence (map ship (map topic status)) :: ship → topic → statusContext examples:
/chat/~sampel-palnet/general— typing in a chat channel/notebook/~sampel-palnet/blog— viewing a notebook/call/~sampel-palnet/room-1— in a voice call/groups/~sampel-palnet/my-group/settings— viewing group settings
+$ action
$% [%set topic=@tas context=path] :: set status (resets timeout)
[%clear topic=@tas context=path] :: explicitly clear
[%clear-all context=path] :: clear all for context
[%heartbeat ~] :: process expired statuses
==| Topic | Timeout | Description |
|---|---|---|
| typing | 10s | Typing indicator |
| viewing | 5min | Active in channel |
| call | ∞* | In voice call (clear on end) |
| listening | 30s | Listening to radio/audio |
*call status cleared explicitly, not via timeout
/presence/[topic]/[...context] :: all ships for topic in context (e.g. /presence/typing/chat/~zod/general)
/presence/ship/[ship] :: all statuses for a specific ship
/presence/context/[...context] :: all topics for a context
/presence/all :: firehose (admin/debug)%chat integration:
:: in %chat's message handler, when receiving typing from network:
=/ valid (validate-sender src.bowl our.bowl msg)
=/ ctx /chat/(scot %p host.nest)/(scot %tas name.nest)
?: valid
(poke-self %presence [%set %typing ctx])
~%groups integration:
:: similar pattern for group contexts
=/ ctx /groups/(scot %p host.flag)/(scot %tas name.flag)/settings
(poke-self %presence [%set %viewing ctx])desk/
├── app/presence.hoon :: agent implementation
├── sur/presence.hoon :: types and structures
├── mar/presence/
│ ├── action.hoon :: mark for actions
│ └── update.hoon :: mark for subscription updates
└── lib/presence.hoon :: helper functions (optional)
Longer-lived availability states that sync between ships via existing profile infrastructure.
Leverage existing %contacts profile sync. No new agent needed—just new fields.
Add to existing contact profile structure:
:: in sur/contacts.hoon, extend +$ contact
+$ contact
$: nickname=@t
bio=@t
status=@t :: existing: custom status text
avatar=(unit @t)
cover=(unit @t)
color=@ux
:: NEW FIELDS
availability=@t :: "online" | "away" | "offline" | "dnd" | ""
last-seen=(unit @da) :: when last active (null if private)
presence-mode=@t :: "visible" | "last-seen-only" | "hidden"
==| State | Meaning | Display |
|---|---|---|
| online | Active now | 🟢 Green dot |
| away | Idle/stepped away | 🟡 Yellow dot |
| offline | Not connected | ⚫ Gray dot |
| dnd | Do not disturb | 🔴 Red dot |
| "" | Not sharing (opted out) | No indicator |
┌─────────────────────────────────────────────────────────────────────┐
│ Availability Sync Flow │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ [My Ship] [Their Ship] │
│ │
│ Client sets availability Profile query returns │
│ │ availability + last-seen │
│ ↓ ↑ │
│ ┌─────────────┐ ┌──────┴──────┐ │
│ │ %contacts │ ── profile ───→ │ %contacts │ │
│ │ (my ship) │ sync │ (their) │ │
│ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Client-side logic (not in agent):
// Pseudocode for client availability management
const IDLE_THRESHOLD = 5 * 60 * 1000; // 5 minutes
const OFFLINE_THRESHOLD = 30 * 60 * 1000; // 30 minutes
let lastActivity = Date.now();
function updateAvailability() {
const idle = Date.now() - lastActivity;
if (idle < IDLE_THRESHOLD) {
setAvailability('online');
} else if (idle < OFFLINE_THRESHOLD) {
setAvailability('away');
} else {
setAvailability('offline');
}
// Also update last-seen unless hidden
if (presenceMode !== 'hidden') {
setLastSeen(Date.now());
}
}Users should have granular control over what they share. Default to visible, but make opting out easy and respected.
+$ presence-mode
$? %visible :: show availability + last-seen + ephemeral
%last-seen-only :: show last-seen only (no live status)
%hidden :: completely invisible
==In addition to the global mode, users can toggle individual features:
| Setting | Default | Description |
|---|---|---|
| share-availability | true | Show online/away/offline |
| share-last-seen | true | Show when last active |
| share-typing | true | Send typing indicators |
| share-viewing | true | Show when viewing a channel |
| show-others-availability | true | See others' availability (mutual) |
| show-others-typing | true | See others' typing indicators |
If implemented, users who opt out of sharing don't see others' status either:
If I hide → I don't see others
If I share → I see others (who share)
Store in %settings-store under presence namespace:
/apps/groups/presence/share-availability
/apps/groups/presence/share-last-seen
/apps/groups/presence/share-typing
/apps/groups/presence/share-viewing
/apps/groups/presence/modeLocation: Settings → Privacy → Presence
┌─────────────────────────────────────────────────────────────────────┐
│ Privacy → Presence │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Presence Mode │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ○ Visible Show everything │ │
│ │ ○ Last-seen Only show when I was last active │ │
│ │ ○ Hidden Don't share any presence info │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Individual Controls (when not Hidden) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ [✓] Share typing indicators │ │
│ │ [✓] Share viewing status │ │
│ │ [✓] Share online/away/offline │ │
│ │ [✓] Share last-seen time │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Note: If you hide your presence, you won't see others' either. │
│ │
└─────────────────────────────────────────────────────────────────────┘
Chat input area:
┌─────────────────────────────────────────────────────────────────────┐
│ ~sampel-palnet is typing... │
├─────────────────────────────────────────────────────────────────────┤
│ [ ] [Send] │
└─────────────────────────────────────────────────────────────────────┘
Multiple people:
~sampel-palnet and ~master-botnet are typing...
~sampel-palnet and 2 others are typing...
Animation: Three bouncing dots (...) or subtle pulse
Sidebar or header:
┌──────────────────────────────────────────────┐
│ #general 👁 3 viewing │
├──────────────────────────────────────────────┤
│ Viewing now: │
│ • ~sampel-palnet │
│ • ~master-botnet │
│ • ~random-person │
└──────────────────────────────────────────────┘
In member lists and DMs:
┌────────────────────────────────┐
│ DIRECT MESSAGES │
│ ┌────────────────────────────┐
│ │ 🟢 ~sampel-palnet │ ← online
│ │ 🟡 ~master-botnet │ ← away
│ │ ⚫ ~random-person │ ← offline
│ │ ~hidden-person │ ← opted out (no dot)
│ └────────────────────────────┘
└────────────────────────────────┘
Profile card / DM header:
┌─────────────────────────────────────────────────────────────────────┐
│ ~sampel-palnet │
│ 🟢 Online • Last seen: just now │
│ Status: "Building presence features" │
└─────────────────────────────────────────────────────────────────────┘
When hidden:
┌─────────────────────────────────────────────────────────────────────┐
│ ~hidden-person │
│ Last seen: — │
└─────────────────────────────────────────────────────────────────────┘
In channel when call active:
┌─────────────────────────────────────────────────────────────────────┐
│ #voice-chat 🔊 3 in call │
├─────────────────────────────────────────────────────────────────────┤
│ In voice: │
│ • ~sampel-palnet (speaking) │
│ • ~master-botnet │
│ • ~random-person (muted) │
└─────────────────────────────────────────────────────────────────────┘
Backend:
- Create %presence agent (
app/presence.hoon,sur/presence.hoon) - Add new fields to %contacts profile structure
- Implement %chat integration for routing presence pokes
- Add %settings-store entries for privacy settings
Frontend:
- Subscribe to %presence updates in relevant views
- Add typing indicator component to chat input
- Add availability dot component
Backend:
- Add %groups integration for viewing status
- Implement heartbeat timer for expiring statuses
- Add privacy mode enforcement
Frontend:
- Typing indicators in chat view
- Availability dots in DM list and member lists
- Profile card availability display
- "X is typing" text above input
Backend:
- Wire up privacy settings to filter what's shared/shown
- Implement mutual visibility logic (optional)
Frontend:
- Privacy settings UI in Settings → Privacy
- Respect hidden users in UI (no placeholder, just absent)
- "X viewers" in channel header
- Animations for typing indicator
- Performance optimization (batch updates)
- Edge cases (reconnection, stale data)
- Mobile parity
-
Mutual visibility: Should hiding your status also hide others from you? (Suggested: yes, for simplicity and fairness)
-
Per-channel/group settings: Should users be able to hide presence in specific channels only? (Suggested: defer to v2)
-
Bot/agent presence: Should Clawdbot and similar agents show typing? (Suggested: yes, opt-in for agents)
-
Read receipts: Out of scope for this PRD, but related. Consider separately.
-
Presence in public channels: Should viewing be visible in large public channels? (Suggested: show count only, not names, above threshold)
- Typing indicators appear within 500ms of user starting to type
- Availability updates propagate within 5s
- <1% false positives on typing (showing when not typing)
- Privacy settings respected 100% of the time
- No presence data leaks for hidden users
|%
+$ topic ?(%typing %viewing %call %listening)
+$ context path :: flexible context path
+$ status [=topic =context expires=@da]
+$ presence (map ship (map topic status))
::
+$ action
$% [%set =topic =context]
[%clear =topic =context]
[%clear-all =context]
[%heartbeat ~]
==
::
+$ update
$% [%set =ship =status]
[%clear =ship =topic =context]
[%full =presence]
==
::
+$ mode ?(%visible %last-seen-only %hidden)
--/+ default-agent, dbug
|%
+$ versioned-state $%(state-0)
+$ state-0 [%0 =presence:sur mode=mode:sur timeouts=(map topic:sur @dr)]
+$ card card:agent:gall
--
%- agent:dbug
^- agent:gall
|_ =bowl:gall
+* this .
def ~(. (default-agent this %.n) bowl)
::
++ on-init
^- (quip card _this)
=/ defaults (malt ~[[%typing ~s10] [%viewing ~m5] [%call *@dr] [%listening ~s30]])
[~ this(state [%0 ~ %visible defaults])]
::
++ on-poke
|= [=mark =vase]
^- (quip card _this)
?> =(src.bowl our.bowl) :: only self-pokes
?+ mark (on-poke:def mark vase)
%presence-action
=/ act !<(action:sur vase)
?- -.act
%set
:: update state, kick subscribers
=/ expires (add now.bowl (~(got by timeouts.state) topic.act))
=/ new-status [topic.act context.act expires]
:: ... update presence map, send updates
[~ this]
::
%clear
:: remove from state, kick subscribers
[~ this]
::
%clear-all
:: clear all for context
[~ this]
::
%heartbeat
:: expire old entries
[~ this]
==
==
::
++ on-watch
|= =path
^- (quip card _this)
?+ path (on-watch:def path)
[%presence %topic @ *]
:: /presence/topic/[topic]/[...context]
[~ this]
::
[%presence %ship @ ~]
:: /presence/ship/[ship]
[~ this]
::
[%presence %context *]
:: /presence/context/[...context]
[~ this]
==
::
++ on-agent on-agent:def
++ on-arvo
|= [=wire =sign-arvo]
^- (quip card _this)
?+ wire (on-arvo:def wire sign-arvo)
[%heartbeat ~]
:: process timer, set next
[~ this]
==
++ on-peek on-peek:def
++ on-leave on-leave:def
++ on-fail on-fail:def
--- Telegram: Online status + last seen + typing
- Discord: Online/idle/dnd + typing + viewing voice
- Slack: Active/away + typing + huddle presence
- Signal: Typing only (privacy-focused)
- WhatsApp: Online/last-seen + typing + read receipts