@glyphteck/veyl 0.67.0 → 0.68.0

package/examples/codex-agent/veyl-channel.js

@@ -0,0 +1,603 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import {
+    open,
+    startSessionRuntime,
+} from '@glyphteck/veyl';
+import { createChatWhitelist } from './chat-whitelist.js';
+
+const ATTACHMENT_TYPES = new Set(['img', 'gif', 'm4a', 'mp4', 'file']);
+const MESSAGE_TYPES = new Set([
+    'txt',
+    'img',
+    'gif',
+    'm4a',
+    'mp4',
+    'file',
+    'req',
+    'rxn',
+    'del',
+]);
+const DEFAULT_TYPING_HEARTBEAT_MS = 2_000;
+const DEFAULT_ATTACHMENT_RETRY_MS = 2_000;
+const DEFAULT_ROUTE_RETRY_MS = 2_000;
+const textEncoder = new TextEncoder();
+
+function cleanText(value) {
+    return String(value ?? '').trim();
+}
+
+function errorSummary(error) {
+    return cleanText(error?.message || error || 'unknown error')
+        .split('\n')[0]
+        .slice(0, 300);
+}
+
+function wait(ms, signal) {
+    if (signal?.aborted) return Promise.resolve();
+    return new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener?.('abort', finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        timer.unref?.();
+        signal?.addEventListener?.('abort', finish, { once: true });
+    });
+}
+
+function publicOwner(peer) {
+    const uid = cleanText(peer?.uid);
+    const chatPK = cleanText(peer?.chatPK).toLowerCase();
+    if (!uid || !/^[0-9a-f]{64}$/u.test(chatPK)) {
+        throw new Error('owner identity is missing a stable uid or chat key');
+    }
+    return Object.freeze({ uid, chatPK });
+}
+
+function ownerMatchesChat(chat, owner) {
+    if (chat?.lineage !== 'direct' || Number(chat?.memberCount) !== 2) {
+        return false;
+    }
+    if (
+        cleanText(chat?.peerUid) === owner.uid
+        && cleanText(chat?.peerChatPK).toLowerCase() === owner.chatPK
+    ) {
+        return true;
+    }
+    const remote = (chat?.members || []).find((member) => (
+        cleanText(member?.uid) === owner.uid
+        && cleanText(member?.chatPK).toLowerCase() === owner.chatPK
+    ));
+    return !!remote;
+}
+
+function ownerMessage(event, owner) {
+    return event?.type === 'message'
+        && event?.message?.from === 'peer'
+        && MESSAGE_TYPES.has(event?.message?.type)
+        && ownerMatchesChat(event.chat, owner)
+        && cleanText(event?.message?.senderChatPK).toLowerCase() === owner.chatPK;
+}
+
+function messageId(event) {
+    return cleanText(event?.message?.id || event?.message?.cid);
+}
+
+function attachmentFilename(event) {
+    const raw = basename(cleanText(event?.message?.name))
+        .replace(/[^a-zA-Z0-9._-]+/gu, '-');
+    return raw.slice(0, 120) || `${event.message.type}-${messageId(event)}`;
+}
+
+function sameBytes(left, right) {
+    return left instanceof Uint8Array
+        && right instanceof Uint8Array
+        && left.byteLength === right.byteLength
+        && left.every((value, index) => value === right[index]);
+}
+
+function plainTextFile(message) {
+    const mime = cleanText(message?.mime || message?.payload?.m).toLowerCase();
+    return message?.type === 'file'
+        && (mime === 'text/plain' || mime.startsWith('text/plain;'));
+}
+
+async function bootAccount(client, options) {
+    const log = typeof options.log === 'function' ? options.log : () => {};
+    log('veyl.account.reading');
+    let account = await client.account.me();
+    if (!account) {
+        const username = cleanText(options.username).replace(/^@+/u, '');
+        if (!username) throw new Error('username required to create the Veyl account');
+        log('veyl.account.creating', { username });
+        await client.account.create({
+            username,
+            network: options.network,
+        });
+        account = await client.account.me();
+    } else if (!account.signedIn) {
+        log('veyl.account.authenticating');
+        account = await client.account.login();
+    }
+    if (!account?.hasVault) {
+        log('veyl.vault.creating');
+        await client.vault.create();
+    } else if (!account.unlocked) {
+        log('veyl.vault.unlocking');
+        await client.vault.unlock();
+    }
+    log('veyl.account.ready');
+    return client.account.me();
+}
+
+class WritingLease {
+    constructor(channel, chatId, compositionId) {
+        this.channel = channel;
+        this.chatId = chatId;
+        this.compositionId = compositionId;
+        this.closed = false;
+        this.timer = null;
+        this.pending = Promise.resolve();
+    }
+
+    async start() {
+        await this.channel.ensureLive(this.chatId);
+        await this.channel.client.chat.markTyping(
+            this.chatId,
+            true,
+            this.compositionId
+        );
+        this.schedule();
+        return this;
+    }
+
+    schedule() {
+        if (this.closed) return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.pending = this.pending
+                .catch(() => {})
+                .then(() => this.channel.client.chat.markTyping(
+                    this.chatId,
+                    true,
+                    this.compositionId
+                ));
+            this.schedule();
+        }, this.channel.typingHeartbeatMs);
+        this.timer.unref?.();
+    }
+
+    pulse() {
+        if (!this.closed && !this.timer) this.schedule();
+    }
+
+    async handoff() {
+        if (this.closed) return;
+        this.closed = true;
+        clearTimeout(this.timer);
+        this.timer = null;
+        await this.pending.catch(() => {});
+        await this.channel.client.chat.markTyping(
+            this.chatId,
+            false,
+            this.compositionId
+        );
+    }
+
+    async clear() {
+        await this.handoff().catch(() => {});
+        await this.channel.client.chat.markTyping(this.chatId, false)
+            .catch(() => {});
+        this.channel.writing.delete(this.chatId);
+    }
+}
+
+export class VeylAgentChannel {
+    constructor(options) {
+        this.client = options.client;
+        this.state = options.state;
+        this.owner = options.owner;
+        this.log = options.log;
+        this.typingHeartbeatMs = options.typingHeartbeatMs;
+        this.attachmentRetryMs = options.attachmentRetryMs;
+        this.routeRetryMs = options.routeRetryMs;
+        this.temporaryRoot = options.temporaryRoot || '';
+        this.temporaryOwner = options.temporaryOwner || null;
+        this.liveChats = new Set();
+        this.writing = new Map();
+        this.temporaryFiles = new Set();
+        this.controller = new AbortController();
+        this.sessionController = new AbortController();
+        this.sessionTask = options.sessionTask || null;
+        this.sessionName = options.sessionName;
+        this.listenTask = null;
+        this.routeChain = Promise.resolve();
+        this.closed = false;
+    }
+
+    async assertTemporaryOwner() {
+        if (!this.temporaryRoot) return;
+        if (typeof this.temporaryOwner?.assertHeld !== 'function') {
+            throw new Error('shared temporary root requires the connector lock');
+        }
+        await this.temporaryOwner.assertHeld();
+    }
+
+    async ensureLive(chatIdValue) {
+        const chatId = cleanText(chatIdValue).toLowerCase();
+        if (!chatId || this.liveChats.has(chatId)) return !!chatId;
+        const result = await this.client.chat.enterLive(chatId);
+        if (result?.entered !== true) {
+            throw new Error(`could not enter Veyl live chat: ${chatId}`);
+        }
+        if (this.closed) {
+            await this.client.chat.leaveLive(chatId);
+            return false;
+        }
+        this.liveChats.add(chatId);
+        return true;
+    }
+
+    async enterExistingOwnerChats() {
+        const chats = await this.client.chat.list({ count: 500 });
+        await Promise.all(chats
+            .filter((chat) => ownerMatchesChat(chat, this.owner))
+            .map((chat) => this.ensureLive(chat.id)));
+    }
+
+    async prepare(event) {
+        const prepared = {
+            event,
+            chatId: cleanText(event?.chat?.id).toLowerCase(),
+            messageId: messageId(event),
+            attachment: null,
+        };
+        if (!ATTACHMENT_TYPES.has(event?.message?.type) || !prepared.messageId) {
+            return prepared;
+        }
+        while (!this.closed) {
+            await this.assertTemporaryOwner();
+            const directory = await mkdtemp(this.temporaryRoot
+                ? join(this.temporaryRoot, 'message-')
+                : join(tmpdir(), 'veyl-agent-'));
+            try {
+                const attachment = await this.client.chat.readAttachmentIn(
+                    prepared.chatId,
+                    prepared.messageId
+                );
+                const path = join(directory, attachmentFilename(event));
+                await writeFile(path, attachment.bytes, { mode: 0o600 });
+                this.temporaryFiles.add(directory);
+                prepared.attachment = {
+                    path,
+                    image: event.message.type === 'img'
+                        || event.message.type === 'gif',
+                };
+                return prepared;
+            } catch (error) {
+                if (
+                    !this.temporaryRoot
+                    || await this.temporaryOwner?.owns?.()
+                ) {
+                    await rm(directory, { recursive: true, force: true })
+                        .catch(() => {});
+                }
+                this.log('veyl.attachment.retry', {
+                    error: errorSummary(error),
+                });
+                await wait(this.attachmentRetryMs, this.controller.signal);
+            }
+        }
+        throw new Error('Veyl agent channel closed');
+    }
+
+    async release(prepared) {
+        const directory = prepared?.attachment?.path
+            ? [...this.temporaryFiles].find((candidate) => (
+                  prepared.attachment.path.startsWith(`${candidate}/`)
+              ))
+            : null;
+        if (!directory) return;
+        try {
+            await this.assertTemporaryOwner();
+        } catch (error) {
+            this.log('veyl.temporary.cleanup.skipped', {
+                error: errorSummary(error),
+            });
+            return;
+        }
+        this.temporaryFiles.delete(directory);
+        await rm(directory, { recursive: true, force: true }).catch(() => {});
+    }
+
+    async beginWriting(prepared, compositionId = '') {
+        const existing = this.writing.get(prepared.chatId);
+        if (existing) return existing;
+        const lease = new WritingLease(
+            this,
+            prepared.chatId,
+            cleanText(compositionId).toLowerCase()
+                || randomBytes(16).toString('hex')
+        );
+        this.writing.set(prepared.chatId, lease);
+        try {
+            return await lease.start();
+        } catch (error) {
+            this.writing.delete(prepared.chatId);
+            throw error;
+        }
+    }
+
+    async send(prepared, text, lease, options = {}) {
+        const message = cleanText(text);
+        if (!message) throw new Error('agent response required');
+        try {
+            const cid = cleanText(options.cid);
+            let reconciled = false;
+            if (cid) {
+                try {
+                    const existing = await this.client.chat.readMessageIn(
+                        prepared.chatId,
+                        cid
+                    );
+                    const found = existing?.message;
+                    const textMatches = found?.type === 'txt'
+                        && found?.text === message;
+                    const attachmentMatches = plainTextFile(found)
+                        && sameBytes(
+                            (await this.client.chat.readAttachmentIn(
+                                prepared.chatId,
+                                cid,
+                                { durableOnly: true }
+                            )).bytes,
+                            textEncoder.encode(message)
+                        );
+                    if (
+                        found?.cid !== cid
+                        || found?.from !== 'self'
+                        || (!textMatches && !attachmentMatches)
+                    ) {
+                        throw new Error('Veyl response cid belongs to different content');
+                    }
+                    reconciled = true;
+                } catch (error) {
+                    if (error?.message !== 'message not found') throw error;
+                }
+            }
+            await lease.handoff();
+            if (!reconciled) {
+                await this.client.chat.sendTo(prepared.chatId, message, {
+                    compositionId: lease.compositionId,
+                    ...(cid ? { cid } : {}),
+                });
+            }
+            this.writing.delete(prepared.chatId);
+        } catch (error) {
+            await lease.clear();
+            throw error;
+        }
+    }
+
+    async react(prepared, emoji, lease) {
+        await lease.clear();
+        await this.client.chat.reactIn(
+            prepared.chatId,
+            prepared.messageId,
+            emoji
+        );
+    }
+
+    markProcessed(events) {
+        const records = events.map((item) => item.event || item);
+        return typeof this.state.complete === 'function'
+            ? this.state.complete(records)
+            : this.state.mark(records);
+    }
+
+    async routeEvent(event, onMessage) {
+        let prepared = null;
+        while (!this.closed && !this.state.has(event)) {
+            try {
+                prepared ||= await this.prepare(event);
+                await this.ensureLive(prepared.chatId);
+                await this.client.chat.markReadIn(prepared.chatId, {
+                    messageId: prepared.messageId,
+                });
+                await onMessage(prepared);
+                return;
+            } catch (error) {
+                this.log('veyl.route.retry', {
+                    error: errorSummary(error),
+                });
+                await wait(this.routeRetryMs, this.controller.signal);
+            }
+        }
+        await this.release(prepared);
+    }
+
+    async listen(onMessage) {
+        if (this.listenTask) return this.listenTask;
+        this.listenTask = this.client.listen({
+            replay: this.state.initialized,
+            chats: 500,
+            transactions: false,
+            read: false,
+            relayReads: false,
+            signal: this.controller.signal,
+            hasReplayCheckpoint: (chat) => this.state.hasChat(chat),
+            isProcessedEvent: (event) => this.state.has(event),
+            onEvent: (event) => {
+                if (event?.type === 'ready') {
+                    void this.state.setInitialized().catch((error) => (
+                        this.log('veyl.state.failed', {
+                            error: errorSummary(error),
+                        })
+                    ));
+                    this.log('veyl.ready', {
+                        profile: event.account?.profile || null,
+                    });
+                    return;
+                }
+                if (event?.type === 'error') {
+                    this.log('veyl.event.error', {
+                        error: cleanText(event.message),
+                    });
+                    return;
+                }
+                if (!ownerMessage(event, this.owner) || this.state.has(event)) {
+                    return;
+                }
+                this.routeChain = this.routeChain
+                    .then(() => this.routeEvent(event, onMessage))
+                    .catch((error) => this.log('veyl.route.failed', {
+                        error: errorSummary(error),
+                    }));
+            },
+        }).finally(async () => {
+            await this.routeChain;
+        });
+        return this.listenTask;
+    }
+
+    async close() {
+        if (this.closed) return;
+        this.closed = true;
+        this.controller.abort();
+        await this.listenTask?.catch(() => {});
+        await Promise.allSettled([...this.writing.values()].map((lease) => (
+            lease.clear()
+        )));
+        await Promise.allSettled([...this.liveChats].map((chatId) => (
+            this.client.chat.leaveLive(chatId)
+        )));
+        this.liveChats.clear();
+        this.sessionController.abort();
+        await this.sessionTask?.catch(() => {});
+        let canCleanTemporaryRoot = true;
+        try {
+            await this.assertTemporaryOwner();
+        } catch (error) {
+            canCleanTemporaryRoot = false;
+            this.log('veyl.temporary.cleanup.skipped', {
+                error: errorSummary(error),
+            });
+        }
+        if (canCleanTemporaryRoot) {
+            await Promise.allSettled([...this.temporaryFiles].map((directory) => (
+                rm(directory, { recursive: true, force: true })
+            )));
+            this.temporaryFiles.clear();
+            if (this.temporaryRoot) {
+                await rm(this.temporaryRoot, { recursive: true, force: true })
+                    .catch(() => {});
+            }
+        }
+        await this.client.close();
+    }
+}
+
+export async function openVeylAgentChannel(options = {}) {
+    if (!options.state) throw new Error('agent state required');
+    const ownerTarget = cleanText(options.owner);
+    if (!ownerTarget) throw new Error('Veyl owner required');
+    const temporaryRoot = cleanText(options.temporaryRoot);
+    if (temporaryRoot) {
+        if (typeof options.temporaryOwner?.assertHeld !== 'function') {
+            throw new Error('shared temporary root requires the connector lock');
+        }
+        await options.temporaryOwner.assertHeld();
+    }
+    let admission = createChatWhitelist([
+        options.state.owner || ownerTarget,
+    ]);
+    const log = typeof options.log === 'function' ? options.log : () => {};
+    const openClient = options.openClient || open;
+    log('veyl.channel.opening');
+    const client = options.client || await openClient({
+        ...(options.clientOptions || {}),
+        homeDir: options.homeDir,
+        profile: options.profile,
+        network: options.network,
+        chat: {
+            ...(options.clientOptions?.chat || {}),
+            incomingChatDecision: (context) => admission(context),
+        },
+    });
+    let channel = null;
+    try {
+        if (temporaryRoot) {
+            await options.temporaryOwner.assertHeld();
+            await rm(temporaryRoot, { recursive: true, force: true });
+            await mkdir(temporaryRoot, { recursive: true, mode: 0o700 });
+        }
+        await bootAccount(client, options);
+        log('veyl.owner.resolving', { owner: ownerTarget });
+        const resolved = await client.peers.show(
+            options.state.owner?.chatPK || ownerTarget
+        );
+        const owner = publicOwner(resolved);
+        await options.state.pinOwner(owner);
+        admission = createChatWhitelist([owner]);
+        log('veyl.admission.publishing');
+        await client.profile.setChatAdmission({
+            direct: 'closed',
+            groups: 'closed',
+            allow: [owner.chatPK],
+        });
+        log('veyl.admission.ready');
+        channel = new VeylAgentChannel({
+            client,
+            state: options.state,
+            owner,
+            log,
+            typingHeartbeatMs: Number(options.typingHeartbeatMs)
+                || DEFAULT_TYPING_HEARTBEAT_MS,
+            attachmentRetryMs: Number(options.attachmentRetryMs)
+                || DEFAULT_ATTACHMENT_RETRY_MS,
+            routeRetryMs: Number(options.routeRetryMs)
+                || DEFAULT_ROUTE_RETRY_MS,
+            temporaryRoot,
+            temporaryOwner: options.temporaryOwner,
+            sessionName: cleanText(options.sessionName) || 'agent',
+        });
+        if (options.serveCli !== false) {
+            let readyResolve;
+            const ready = new Promise((resolve) => {
+                readyResolve = resolve;
+            });
+            channel.sessionTask = startSessionRuntime(client, {
+                profile: options.profile,
+                name: channel.sessionName,
+                signal: channel.sessionController.signal,
+                onReady: readyResolve,
+            });
+            log('veyl.cli.starting', { session: channel.sessionName });
+            await Promise.race([
+                ready,
+                channel.sessionTask.then(() => {
+                    throw new Error('Veyl CLI session stopped before it became ready');
+                }),
+            ]);
+            log('veyl.cli.ready', { session: channel.sessionName });
+        }
+        log('veyl.owner_chats.entering');
+        await channel.enterExistingOwnerChats();
+        log('veyl.channel.ready');
+        return channel;
+    } catch (error) {
+        if (channel) {
+            await channel.close().catch(() => {});
+        } else {
+            await client.close().catch(() => {});
+            if (temporaryRoot && await options.temporaryOwner?.owns?.()) {
+                await rm(temporaryRoot, { recursive: true, force: true })
+                    .catch(() => {});
+            }
+        }
+        throw error;
+    }
+}

package/package.json

@@ -26,6 +26,17 @@
         "examples/bot-fleet/policy.js",
         "examples/bot-fleet/runtime.js",
         "examples/bot-fleet/readme.md",
+        "examples/codex-agent/agent-instructions.js",
+        "examples/codex-agent/agent-state.js",
+        "examples/codex-agent/chat-whitelist.js",
+        "examples/codex-agent/codex-app-server.js",
+        "examples/codex-agent/codex-config.js",
+        "examples/codex-agent/codex-input.js",
+        "examples/codex-agent/connector.js",
+        "examples/codex-agent/index.js",
+        "examples/codex-agent/instance-lock.js",
+        "examples/codex-agent/readme.md",
+        "examples/codex-agent/veyl-channel.js",
         "LICENSE",
         "readme.md",
         "package.json"
@@ -42,5 +53,5 @@
         "start": "node src/cli.js",
         "lint": "eslint src --quiet"
     },
-    "version": "0.67.0"
+    "version": "0.68.0"
 }

package/readme.md

@@ -54,6 +54,7 @@ Run `bunx veyl help` for the full command list. Long-running agents should keep
 - [JavaScript API](docs/api.md)
 - [CLI reference](docs/cli.md)
 - [agent operation](docs/agents.md)
+- [single-account Codex agent](examples/codex-agent/readme.md)
 - [MCP documentation discovery](docs/discovery.md)
 
 ## license