@glyphteck/veyl 0.60.0 → 0.61.0

package/docs/agents.md

@@ -52,7 +52,7 @@ await veyl.listen({
 });
 ```
 
-This is a live subscription to shared chat-list and transfer state, not a polling loop. By default it emits compact peer-authored events and opens a changed chat only long enough to process it, so hundreds of peers do not become hundreds of retained message listeners. Set `compact: false` or `incomingOnly: false` when complete payloads or self-authored messages are required. A long-lived fleet can opt into `persistentChats: true` with `persistentChatIdleMs` to keep active conversations mounted, mark peer messages read before policy effects, and release only idle conversations; the account-level chat-list subscription reopens them when new activity arrives. Each listener has independent replay/filter state. Slow callbacks should hand work to an application queue if they must preserve event throughput.
+This is a live subscription to shared chat-list and transfer state, not a polling loop. By default it emits compact peer-authored events and opens a changed chat only long enough to process it, so hundreds of peers do not become hundreds of retained message listeners. Set `compact: false` or `incomingOnly: false` when complete payloads or self-authored messages are required. A long-lived fleet can opt into `persistentChats: true` with `persistentChatIdleMs` to keep active conversations mounted and release only idle conversations; the account-level chat-list subscription reopens them when new activity arrives. Set `relayReads: true` with `read: true` when the listener itself represents viewing: it briefly joins the ordinary encrypted live room, advances from the already-decrypted message before emitting the event, and coalesces durable receipt writes without a second message lookup. Each listener has independent replay/filter state. Slow callbacks should hand work to an application queue if they must preserve event throughput.
 
 Compact message events include stable `chatId`, verified sender identity, member summaries, and reusable `replyTo` and `reactTo` targets. Transaction events carry the same simplified transfer shape returned by wallet history.
 

package/docs/api.md

@@ -435,7 +435,7 @@ await veyl.listen({
 });
 ```
 
-`listen` subscribes to the shared live chat-list and transfer-store owners. It emits `ready`, `message`, `message-delete`, `transaction`, and `error` events. Message events carry a stable `chatId`, verified actor/member summaries, and a qualified message target. Compact, incoming-only events and transient chat subscriptions are the defaults: the encrypted chat list acts as a wake index, so a changed chat opens briefly, processes its current and history pages, and releases instead of retaining one listener per chat. Set `compact: false`, `incomingOnly: false`, or `persistentChats: true` only when the caller needs those broader behaviors.
+`listen` subscribes to the shared live chat-list and transfer-store owners. It emits `ready`, `message`, `message-delete`, `transaction`, and `error` events. Message events carry a stable `chatId`, verified actor/member summaries, and a qualified message target. Compact, incoming-only events and transient chat subscriptions are the defaults: the encrypted chat list acts as a wake index, so a changed chat opens briefly, processes its current and history pages, and releases instead of retaining one listener per chat. Set `compact: false`, `incomingOnly: false`, or `persistentChats: true` only when the caller needs those broader behaviors. A headless viewer may set `read: true, relayReads: true`; the listener then advances each peer read from its existing decrypted batch through a short encrypted live-room lease before emitting the event, while the durable write remains coalesced.
 
 Use `listen` for account-wide agent wakeups. Use `chat.enterById` when an agent is actively inside any notes/direct/group chat; use `chat.enter(peer)` only as a canonical-direct convenience.
 

package/examples/bot-fleet/policy.js

@@ -1,11 +1,19 @@
 import { createHash } from 'node:crypto';
 
-export const BOT_FLEET_ROLES = new Set(['read', 'echo', 'faucet', 'traffic']);
+export const BOT_FLEET_ROLES = new Set([
+    'read',
+    'echo',
+    'faucet',
+    'traffic',
+    'live',
+    'typing',
+]);
 const BOT_UNDERFUNDED_TEXT = 'insufficient funds';
 const ATTACHMENT_TYPES = new Set(['img', 'gif', 'm4a', 'mp4', 'file']);
 const NORMAL_CLAIM_INTERVAL_MS = 5 * 60_000;
 const FAUCET_CLAIM_INTERVAL_MS = 30_000;
 const MAX_CLAIM_BACKOFF_MS = 2 * 60_000;
+const TYPING_HEARTBEAT_MS = 2_000;
 
 function rolesFor(account) {
     return new Set(account?.roles || []);
@@ -64,6 +72,9 @@ function assertRoles(account) {
     if ((roles.has('echo') || roles.has('faucet')) && !roles.has('read')) {
         throw new Error('echo and faucet bot roles require read');
     }
+    if (roles.has('typing') && !roles.has('live')) {
+        throw new Error('typing bot role requires live');
+    }
     return roles;
 }
 
@@ -108,12 +119,19 @@ function sendAttachmentToEventChat(client, event, attachment, options) {
         : client.chat.sendAttachment(event.peer, attachment, options);
 }
 
-function markEventChatRead(client, event) {
-    const options = { messageId: event.message.id };
-    const chatId = eventChatId(event);
-    return chatId
-        ? client.chat.markReadIn(chatId, options)
-        : client.chat.markRead(event.peer, options);
+function groupEchoWinner(event, echoChatKeys) {
+    const eligible = [...new Set(
+        (event?.chat?.members || [])
+            .map((member) => chatKey(member?.chatPK))
+            .filter((key) => key && echoChatKeys.has(key))
+    )].sort();
+    const source = eventId(event);
+    if (!source || !eligible.length) return '';
+    const bucket = createHash('sha256')
+        .update(source)
+        .digest()
+        .readUInt32BE(0);
+    return eligible[bucket % eligible.length];
 }
 
 async function runAction(
@@ -355,6 +373,96 @@ async function stopClaimLoop(profile, states) {
     await state.pending;
 }
 
+function typingCompositionId(account, chatId) {
+    return createHash('sha256')
+        .update(`${account.profile}\n${chatId}\ntyping`)
+        .digest('hex')
+        .slice(0, 32);
+}
+
+async function ensureLiveChat(account, state, chatId) {
+    const id = String(chatId || '').trim().toLowerCase();
+    if (!id || state.chatIds.has(id)) return false;
+    const pending = state.entering.get(id);
+    if (pending) return pending;
+    const entering = state.client.chat.enterLive(id)
+        .then(async (result) => {
+            if (!result?.entered) return false;
+            if (state.closed) {
+                await state.client.chat.leaveLive(id);
+                return false;
+            }
+            state.chatIds.add(id);
+            if (state.typing) {
+                await state.client.chat.markTyping(
+                    id,
+                    true,
+                    typingCompositionId(account, id)
+                );
+            }
+            return true;
+        })
+        .finally(() => state.entering.delete(id));
+    state.entering.set(id, entering);
+    return entering;
+}
+
+function scheduleTypingHeartbeat(account, state) {
+    if (!state.typing || state.closed) return;
+    state.timer = setTimeout(() => {
+        state.pending = Promise.allSettled([...state.chatIds].map((chatId) =>
+            state.client.chat.markTyping(
+                chatId,
+                true,
+                typingCompositionId(account, chatId)
+            )
+        )).finally(() => scheduleTypingHeartbeat(account, state));
+    }, TYPING_HEARTBEAT_MS);
+    state.timer.unref?.();
+}
+
+async function startLiveRole(account, client, states) {
+    const roles = rolesFor(account);
+    const state = {
+        chatIds: new Set(),
+        client,
+        closed: false,
+        entering: new Map(),
+        pending: Promise.resolve(),
+        timer: null,
+        typing: roles.has('typing'),
+    };
+    states.set(account.profile, state);
+    try {
+        const chats = await client.chat.list({ count: 500 });
+        await Promise.all(chats.map((chat) => ensureLiveChat(account, state, chat.id)));
+        scheduleTypingHeartbeat(account, state);
+    } catch (error) {
+        await stopLiveRole(account, states);
+        throw error;
+    }
+}
+
+async function stopLiveRole(account, states) {
+    const state = states.get(account.profile);
+    states.delete(account.profile);
+    if (!state) return;
+    state.closed = true;
+    clearTimeout(state.timer);
+    await Promise.allSettled(state.entering.values());
+    await state.pending.catch(() => {});
+    await Promise.allSettled([...state.chatIds].map(async (chatId) => {
+        if (state.typing) {
+            await state.client.chat.markTyping(
+                chatId,
+                false,
+                typingCompositionId(account, chatId)
+            );
+        }
+        await state.client.chat.leaveLive(chatId);
+    }));
+}
+
 export function createBotFleetPolicy(options = {}) {
     const journal = options.journal || null;
     const checkpoint = options.checkpoint || null;
@@ -367,9 +475,11 @@ export function createBotFleetPolicy(options = {}) {
     const usernameByProfile = new Map();
     const responderProfiles = new Set();
     const chatKeyByProfile = new Map();
+    const echoChatKeys = new Set();
     const claimStates = new Map();
+    const liveStates = new Map();
 
-    function shouldMirror(event) {
+    function shouldMirror(account, event) {
         if (isFleetGeneratedMessage(event)) return false;
         if (!isGroupMessage(event)) {
             return !managedUsernames.has(usernameTarget(event.peer));
@@ -382,7 +492,10 @@ export function createBotFleetPolicy(options = {}) {
         }
         const senderChatPK = chatKey(event.message?.senderChatPK);
         if (!senderChatPK) return false;
-        return !managedChatKeys.has(senderChatPK);
+        if (managedChatKeys.has(senderChatPK)) return false;
+        const accountChatPK = chatKeyByProfile.get(account.profile);
+        return !!accountChatPK
+            && groupEchoWinner(event, echoChatKeys) === accountChatPK;
     }
 
     return Object.freeze({
@@ -391,6 +504,7 @@ export function createBotFleetPolicy(options = {}) {
             managedChatKeys.clear();
             responderProfiles.clear();
             chatKeyByProfile.clear();
+            echoChatKeys.clear();
             for (const profile of profiles) {
                 assertRoles(profile);
                 if (!canRespond(profile)) continue;
@@ -402,7 +516,7 @@ export function createBotFleetPolicy(options = {}) {
             }
         },
         async start({ account, client }) {
-            assertRoles(account);
+            const roles = assertRoles(account);
             const current = await client.account.me();
             const username = usernameTarget(current?.username);
             if (!username) {
@@ -427,29 +541,40 @@ export function createBotFleetPolicy(options = {}) {
                 responderProfiles.add(account.profile);
                 chatKeyByProfile.set(account.profile, accountChatPK);
                 managedChatKeys.add(accountChatPK);
+                if (roles.has('echo')) echoChatKeys.add(accountChatPK);
                 managedUsernames.add(username);
             }
             if (!baseline) {
                 startClaimLoop(account, client, claimStates);
+                if (roles.has('live')) {
+                    await startLiveRole(account, client, liveStates);
+                }
             }
         },
         async stop({ account }) {
+            await stopLiveRole(account, liveStates);
             await stopClaimLoop(account.profile, claimStates);
             const username = usernameByProfile.get(account.profile);
             const accountChatPK = chatKeyByProfile.get(account.profile);
             usernameByProfile.delete(account.profile);
             chatKeyByProfile.delete(account.profile);
             if (accountChatPK) managedChatKeys.delete(accountChatPK);
+            if (accountChatPK) echoChatKeys.delete(accountChatPK);
             if (username) managedUsernames.delete(username);
         },
         async stopFleet() {
+            await Promise.all([...liveStates.keys()].map((profile) =>
+                stopLiveRole({ profile, roles: [] }, liveStates)
+            ));
             managedUsernames.clear();
             managedChatKeys.clear();
             responderProfiles.clear();
             chatKeyByProfile.clear();
+            echoChatKeys.clear();
             await checkpoint?.flush();
         },
         async onEvent({ account, client, event }) {
+            const roles = rolesFor(account);
             if (checkpoint?.has(account.profile, event)) {
                 return null;
             }
@@ -459,9 +584,7 @@ export function createBotFleetPolicy(options = {}) {
                 });
                 return null;
             }
-            const roles = rolesFor(account);
             let result = null;
-            let markRead = false;
             if (event?.type === 'transaction') {
                 result = await client.wallet.claim({ count: 100 });
             } else if (
@@ -469,7 +592,6 @@ export function createBotFleetPolicy(options = {}) {
                 event.message?.from === 'peer' &&
                 roles.has('read')
             ) {
-                markRead = true;
                 if (
                     roles.has('faucet') &&
                     event.message.type === 'req'
@@ -482,7 +604,7 @@ export function createBotFleetPolicy(options = {}) {
                     );
                 } else if (
                     roles.has('echo') &&
-                    shouldMirror(event)
+                    shouldMirror(account, event)
                 ) {
                     result = await mirrorEcho(
                         journal,
@@ -492,9 +614,6 @@ export function createBotFleetPolicy(options = {}) {
                     );
                 }
             }
-            if (markRead) {
-                await markEventChatRead(client, event);
-            }
             await checkpoint?.mark(account.profile, event);
             return result;
         },

package/examples/bot-fleet/readme.md

@@ -6,10 +6,12 @@ The secret-free version-2 manifest stores account indices, usernames, networks,
 
 ## Roles
 
-- `read` subscribes through the public live-event API, marks peer messages read before policy effects run, and keeps active conversations mounted. A conversation with no activity is released after the configured idle window so inactive peers do not keep a message listener open; the account-level chat-list subscription reopens it when new activity arrives.
-- `echo` mirrors text, encrypted attachments, and payment requests with deterministic action ids.
+- `read` subscribes through the public event API and advances directly from the listener's newest decrypted activity before enabled effects run, including a bot's own confirmed reply. The canonical runtime keeps that chat's ordinary encrypted live room for five idle minutes, flushes an already-connected relay frontier before emitting the event, lets a cold room publish its frontier in the initial socket snapshot without waiting on the handshake, coalesces the durable write, and never acquires a lease for checkpointed startup history. The event checkpoint remains post-effect for safe replay.
+- `echo` mirrors text, encrypted attachments, and payment requests with deterministic action ids. Group members derive exactly one source-specific eligible fleet echo from the encrypted roster for each source message; every other echo remains silent and only reads. Selection distributes independently across messages, so the same bot may legitimately win consecutive messages.
 - `faucet` pays valid requests through the public wallet API and journals caller operation ids.
 - `traffic` is an eligibility marker for an external local operator policy; it performs no work by itself.
+- `live` holds the account's normal encrypted live-room connection in each chat without advancing read state or sending messages.
+- `typing` requires `live` and continually renews one stable composition through the same encrypted live state until the policy stops.
 
 Only response-capable fleet peers are loop-suppressed. Incoming transaction events and staggered fallback loops call the public wallet claim method. Startup replays a bounded visible window; an event checkpoint suppresses completed source messages, while the action journal suppresses completed effects and stops ambiguous payments for explicit reconciliation.
 
@@ -29,7 +31,7 @@ The bounded live harness is opt-in because it creates and deletes real REGTEST a
 bun check:bot-fleet-live
 ```
 
-It uses a separate random local home, proves creation/recovery, text/request/attachment echo, retention, post-policy reads, faucet behavior, transfer claim, restart, final balance reconciliation, and normal SDK account deletion. An interrupted run prints the disposable manifest path and can resume with `VEYL_LIVE_BOT_FLEET_MANIFEST=/absolute/path/to/manifest.json bun check:bot-fleet-live`.
+It uses a separate random local home, proves creation/recovery, text/request/attachment echo, retention, immediate reads with post-policy checkpoints, faucet behavior, transfer claim, restart, final balance reconciliation, and normal SDK account deletion. An interrupted run prints the disposable manifest path and can resume with `VEYL_LIVE_BOT_FLEET_MANIFEST=/absolute/path/to/manifest.json bun check:bot-fleet-live`.
 
 Reserved usernames require an owner-only namespace key. Provisioning signs a short-lived claim bound to the exact derived machine credential; the key is never accepted through argv, environment variables, or the manifest.
 

package/examples/bot-fleet/runtime.js

@@ -4,6 +4,7 @@ import {
     openFleetOwner,
 } from '@glyphteck/veyl';
 let policyRevision = 0;
+const DEFAULT_READ_LIVE_IDLE_MS = 5 * 60_000;
 
 async function loadBotFleetPolicy(options) {
     policyRevision += 1;
@@ -22,11 +23,14 @@ export async function createExampleBotFleetRuntime(options = {}) {
         policies: [],
         eventOptions: async (profile) => ({
             replay: true,
-            chats: profile.roles.includes('read'),
+            chats: profile.roles.includes('read') || profile.roles.includes('live'),
             persistentChats: true,
             persistentChatIdleMs: options.persistentChatIdleMs || 5 * 60_000,
             transactions: true,
-            read: true,
+            read: profile.roles.includes('read'),
+            relayReads: profile.roles.includes('read'),
+            readLiveIdleMs:
+                options.readLiveIdleMs ?? DEFAULT_READ_LIVE_IDLE_MS,
             chatCount: options.chatCount || 500,
             messageCount: options.messageCount || 20,
             replayMessageLimit: options.replayMessageLimit || 500,

package/package.json

@@ -41,5 +41,5 @@
         "start": "node src/cli.js",
         "lint": "eslint src --quiet"
     },
-    "version": "0.60.0"
+    "version": "0.61.0"
 }