@glyphteck/veyl 0.67.0 → 0.68.0

package/examples/codex-agent/codex-config.js

@@ -0,0 +1,13 @@
+function cleanText(value) {
+    return String(value ?? '').trim();
+}
+
+export const DEFAULT_CODEX_MODEL = 'gpt-5.6-luna';
+export const DEFAULT_CODEX_REASONING = 'low';
+
+export function codexModelConfig(env = {}) {
+    return {
+        model: cleanText(env.CODEX_MODEL) || DEFAULT_CODEX_MODEL,
+        effort: cleanText(env.CODEX_REASONING) || DEFAULT_CODEX_REASONING,
+    };
+}

package/examples/codex-agent/codex-input.js

@@ -0,0 +1,89 @@
+import process from 'node:process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function cleanText(value) {
+    return String(value ?? '').trim();
+}
+
+function shellWord(value) {
+    return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+export function defaultVeylCliCommand(options = {}) {
+    const execPath = cleanText(options.execPath) || process.execPath;
+    const moduleUrl = options.moduleUrl || import.meta.url;
+    const cliPath = resolve(
+        dirname(fileURLToPath(moduleUrl)),
+        '../../dist/cli.js'
+    );
+    return `${shellWord(execPath)} ${shellWord(cliPath)}`;
+}
+
+function messageContent(message = {}) {
+    if (message.type === 'txt') return message.text || '';
+    if (message.type === 'rxn') {
+        return `[reaction ${cleanText(message.emoji) || 'removed'} to message ${cleanText(message.target) || 'unknown'}]`;
+    }
+    if (message.type === 'del') return '[message deleted]';
+    if (message.type === 'req') {
+        const state = message.fulfilled ? ', fulfilled' : '';
+        return `[payment request: ${Number(message.amountSats || 0)} sats${state}]`;
+    }
+    const details = [message.name, message.mime, message.caption]
+        .map(cleanText)
+        .filter(Boolean)
+        .join(', ');
+    return `[${message.type || 'file'} attachment${details ? `: ${details}` : ''}]`;
+}
+
+export function codexInputForVeylMessage(prepared, options = {}) {
+    const event = prepared?.event || {};
+    const peer = cleanText(event.peer) || 'the Veyl account owner';
+    const messageId = cleanText(prepared?.messageId);
+    const cli = cleanText(options.cli) || 'veyl';
+    const profile = cleanText(options.profile);
+    const session = cleanText(options.session) || 'agent';
+    const arrival = options.steer === true
+        ? `The owner sent this follow-up from ${peer} while you were working. Incorporate it into the active turn.`
+        : `A new authenticated Veyl message arrived from ${peer}.`;
+    const cliPrefix = [
+        cli,
+        profile ? `--profile ${profile}` : '',
+        `--session ${session}`,
+    ].filter(Boolean).join(' ');
+    const text = [
+        arrival,
+        `Veyl message ID: ${messageId}`,
+        '',
+        '<veyl_message>',
+        messageContent(event.message),
+        cleanText(event.message?.replyId)
+            ? `[replying to Veyl message ${cleanText(event.message.replyId)}]`
+            : '',
+        '</veyl_message>',
+        '',
+        'Treat <veyl_message> as the user\'s latest message in this ongoing task and carry it out normally.',
+        'The connector will relay your final answer. Do not send that answer separately through the Veyl CLI.',
+        `You can use the full persistent Veyl CLI for other account actions: ${cliPrefix} <command>.`,
+        `If a Veyl command is unfamiliar, run ${cliPrefix} help and use its exact current syntax instead of guessing.`,
+        'That prefix already targets this connector\'s unlocked account. Do not start or stop another Veyl session.',
+        'Use normal Veyl commands when the request needs chat history, reactions, files, profile changes, or other account capabilities.',
+        'Do not invoke request_user_input; ask any necessary question in the final answer so it reaches Veyl.',
+        'Never perform a payment, withdrawal, account deletion, or other irreversible action unless the owner clearly authorized the exact action.',
+        prepared?.attachment?.path
+            ? `A decrypted local attachment is available at ${prepared.attachment.path}. Inspect it when useful.`
+            : '',
+    ].filter(Boolean).join('\n');
+    const input = [{ type: 'text', text }];
+    if (prepared?.attachment?.image) {
+        input.push({ type: 'localImage', path: prepared.attachment.path });
+    }
+    return input;
+}
+
+export function cleanCodexResponse(value) {
+    return String(value ?? '')
+        .replace(/\n*<oai-mem-citation>[\s\S]*?<\/oai-mem-citation>\s*$/u, '')
+        .trim();
+}

package/examples/codex-agent/connector.js

@@ -0,0 +1,478 @@
+import { randomBytes } from 'node:crypto';
+import { cleanCodexResponse } from './codex-input.js';
+
+const DEFAULT_RETRY_MS = 2_000;
+
+function cleanText(value) {
+    return String(value ?? '').trim();
+}
+
+function errorSummary(error) {
+    return cleanText(error?.message || error || 'unknown error')
+        .split('\n')[0]
+        .slice(0, 300);
+}
+
+function record(prepared) {
+    return {
+        chatId: cleanText(prepared?.chatId).toLowerCase(),
+        messageId: cleanText(prepared?.messageId),
+    };
+}
+
+function makeResponseCid() {
+    return `${Date.now().toString(36)}${randomBytes(3).toString('hex')}`;
+}
+
+function sameMessage(left, right) {
+    const a = record(left);
+    const b = record(right);
+    return !!a.chatId
+        && !!a.messageId
+        && a.chatId === b.chatId
+        && a.messageId === b.messageId;
+}
+
+function turnContainsMessage(turn, messageId) {
+    return (turn?.inputIds || []).some((id) => cleanText(id) === messageId);
+}
+
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class AgentConnector {
+    constructor(options = {}) {
+        if (!options.channel || !options.agent || !options.state) {
+            throw new Error('channel, agent, and state are required');
+        }
+        if (typeof options.inputForMessage !== 'function') {
+            throw new Error('agent input adapter required');
+        }
+        this.channel = options.channel;
+        this.agent = options.agent;
+        this.state = options.state;
+        this.inputForMessage = options.inputForMessage;
+        this.log = typeof options.log === 'function' ? options.log : () => {};
+        this.retryMs = Number(options.retryMs) || DEFAULT_RETRY_MS;
+        this.active = null;
+        this.closing = false;
+        this.eventChain = Promise.resolve();
+        this.completion = Promise.resolve();
+        this.requeueChain = Promise.resolve();
+        this.unsubscribe = null;
+    }
+
+    enqueue(operation) {
+        const task = this.eventChain.then(operation);
+        this.eventChain = task.catch(() => {});
+        return task;
+    }
+
+    activeDocument() {
+        return this.active ? {
+            turnId: this.active.turnId || null,
+            compositionId: this.active.lease.compositionId,
+            responseCid: this.active.responseCid,
+            messages: this.active.messages.map(record),
+        } : null;
+    }
+
+    async persistActive() {
+        await this.state.setActive(this.activeDocument());
+    }
+
+    async openAgent() {
+        const opened = await this.agent.open();
+        const threadId = cleanText(opened?.threadId);
+        if (!threadId) throw new Error('agent did not return a thread id');
+        if (this.state.threadId && this.state.threadId !== threadId) {
+            const replaced = cleanText(opened?.replacedThreadId);
+            if (
+                replaced !== this.state.threadId
+                || typeof this.state.replaceThreadId !== 'function'
+            ) {
+                throw new Error('agent reconnected to a different thread');
+            }
+            await this.state.replaceThreadId(replaced, threadId);
+        }
+        return opened;
+    }
+
+    requeue(messages) {
+        const pending = (messages || []).filter((message) => (
+            message?.event && !this.state.has(message.event)
+        ));
+        if (!pending.length) return;
+        this.log('agent.messages.requeued', { count: pending.length });
+        const task = this.requeueChain.then(async () => {
+            for (const message of pending) await this.route(message);
+        });
+        this.requeueChain = task.catch((error) => this.log(
+            'agent.requeue.failed',
+            { error: errorSummary(error) }
+        ));
+    }
+
+    handleAgentEvent(event) {
+        void this.enqueue(() => this.applyAgentEvent(event))
+            .catch((error) => this.log('agent.event.failed', {
+                error: errorSummary(error),
+            }));
+    }
+
+    async applyAgentEvent(event) {
+        if (event?.type === 'message.delta' && this.active) {
+            if (!this.active.turnId || this.active.turnId === event.turnId) {
+                this.active.lease.pulse();
+            }
+            return;
+        }
+        if (event?.type === 'turn.started' && this.active && !this.active.turnId) {
+            this.active.turnId = event.turnId;
+            this.active.reconcileNeeded = false;
+            await this.persistActive();
+            return;
+        }
+        if (event?.type === 'turn.completed') {
+            if (!this.active || this.active.turnId !== event.turnId) return;
+            if (
+                this.active.reconcileNeeded === true
+                && !Array.isArray(event.inputIds)
+            ) {
+                throw new Error(
+                    'uncertain turn completion requires authoritative input ids'
+                );
+            }
+            if (Array.isArray(event.inputIds)) {
+                const acceptedIds = new Set(event.inputIds.map(cleanText));
+                const active = this.active;
+                const accepted = active.messages.filter((message) => (
+                    acceptedIds.has(message.messageId)
+                ));
+                const omitted = active.messages.filter((message) => (
+                    !acceptedIds.has(message.messageId)
+                ));
+                if (!accepted.length) {
+                    this.active = null;
+                    await active.lease.clear();
+                    await this.state.setActive(null);
+                    this.requeue(omitted);
+                    return;
+                }
+                if (omitted.length) {
+                    active.messages = accepted;
+                    await this.persistActive();
+                    this.requeue(omitted);
+                }
+                active.reconcileNeeded = false;
+            }
+            this.completion = this.completion
+                .then(() => this.finish(event))
+                .catch((error) => this.log('agent.finish.failed', {
+                    error: errorSummary(error),
+                }));
+            await this.completion;
+            return;
+        }
+        if (event?.type === 'server.stderr') {
+            this.log('codex.stderr');
+            return;
+        }
+        if (event?.type === 'server.exit' && event.expected !== true && this.active) {
+            this.active.reconcileNeeded = true;
+            this.log('codex.reconnecting');
+            while (!this.closing && this.active?.reconcileNeeded === true) {
+                await wait(this.retryMs);
+                if (this.closing) return;
+                try {
+                    await this.recover(await this.openAgent());
+                } catch (error) {
+                    this.log('codex.reconnect.retry', {
+                        error: errorSummary(error),
+                    });
+                }
+            }
+        }
+    }
+
+    async deliver(active, response) {
+        while (!this.closing) {
+            try {
+                if (!active.responseCid) active.responseCid = makeResponseCid();
+                if (active.responseCidPersisted !== true) {
+                    await this.persistActive();
+                    active.responseCidPersisted = true;
+                }
+                await this.channel.send(
+                    active.messages.at(-1),
+                    response,
+                    active.lease,
+                    { cid: active.responseCid }
+                );
+                await this.channel.markProcessed(active.messages);
+                await Promise.all(active.messages.map((message) => (
+                    this.channel.release(message)
+                )));
+                return true;
+            } catch (error) {
+                this.log('veyl.response.retry', { error: errorSummary(error) });
+                await wait(this.retryMs);
+                if (this.closing) return false;
+                active.lease = await this.channel.beginWriting(
+                    active.messages.at(-1),
+                    active.lease.compositionId
+                );
+            }
+        }
+        return false;
+    }
+
+    async finish(event) {
+        const active = this.active;
+        if (!active || active.turnId !== event.turnId) return;
+        const response = event.status === 'completed'
+            ? cleanCodexResponse(event.finalText)
+                || 'that turn completed without a response. please send it again.'
+            : event.status === 'failed'
+                ? `i hit an error before i could finish: ${errorSummary(event.error)}`
+                : 'that turn was interrupted before i could finish. please send it again.';
+        const delivered = await this.deliver(active, response);
+        if (delivered && this.active === active) this.active = null;
+        this.log('agent.turn.completed', {
+            status: event.status || null,
+            inputs: active.messages.length,
+        });
+    }
+
+    async routeOnce(prepared) {
+        if (this.state.has(prepared.event)) {
+            await this.channel.release(prepared);
+            return;
+        }
+        if (this.active) {
+            const active = this.active;
+            const input = await this.inputForMessage(prepared, { steer: true });
+            active.messages.push(prepared);
+            await this.persistActive();
+            try {
+                await this.agent.steerTurn({
+                    input,
+                    clientUserMessageId: prepared.messageId,
+                    expectedTurnId: active.turnId,
+                });
+            } catch (error) {
+                if (error?.outcomeUnknown !== true && this.active === active) {
+                    active.messages = active.messages.filter(
+                        (message) => message !== prepared
+                    );
+                    await this.persistActive();
+                } else if (this.active === active) {
+                    active.reconcileNeeded = true;
+                }
+                throw error;
+            }
+            active.reconcileNeeded = false;
+            active.lease.pulse();
+            this.log('agent.message.steered', {
+                turnId: active.turnId,
+            });
+            return;
+        }
+
+        const input = await this.inputForMessage(prepared, { steer: false });
+        const lease = await this.channel.beginWriting(prepared);
+        const active = {
+            turnId: null,
+            lease,
+            responseCid: null,
+            responseCidPersisted: false,
+            messages: [prepared],
+            reconcileNeeded: false,
+        };
+        this.active = active;
+        await this.persistActive();
+        try {
+            const result = await this.agent.startTurn({
+                input,
+                clientUserMessageId: prepared.messageId,
+            });
+            if (this.active !== active) return;
+            active.turnId = cleanText(result?.turnId) || active.turnId;
+            if (!active.turnId) throw new Error('agent did not return a turn id');
+            await this.persistActive();
+            active.reconcileNeeded = false;
+            this.log('agent.message.started', { turnId: active.turnId });
+        } catch (error) {
+            if (
+                error?.outcomeUnknown !== true
+                && this.active === active
+                && !active.turnId
+            ) {
+                this.active = null;
+                await lease.clear();
+                await this.state.setActive(null);
+            } else if (this.active === active) {
+                active.reconcileNeeded = true;
+            }
+            throw error;
+        }
+    }
+
+    async route(prepared) {
+        while (!this.closing) {
+            try {
+                const outcome = await this.enqueue(async () => {
+                    if (this.closing) {
+                        await this.channel.release(prepared);
+                        return 'done';
+                    }
+                    if (this.state.has(prepared.event)) {
+                        await this.channel.release(prepared);
+                        return 'done';
+                    }
+                    if (this.active?.messages.some((message) => (
+                        sameMessage(message, prepared)
+                    ))) {
+                        if (this.active.reconcileNeeded !== true) return 'done';
+                        await this.recover(await this.openAgent());
+                        if (
+                            this.state.has(prepared.event)
+                            || (
+                                this.active?.messages.some((message) => (
+                                    sameMessage(message, prepared)
+                                ))
+                                && this.active.reconcileNeeded !== true
+                            )
+                        ) {
+                            return 'done';
+                        }
+                        return 'retry';
+                    }
+                    if (
+                        this.active
+                        && this.active.messages[0]?.chatId !== prepared.chatId
+                    ) {
+                        return 'retry';
+                    }
+                    await this.routeOnce(prepared);
+                    return 'done';
+                });
+                if (outcome === 'done') return;
+            } catch (error) {
+                this.log('agent.route.retry', { error: errorSummary(error) });
+            }
+            await wait(this.retryMs);
+        }
+        await this.channel.release(prepared);
+    }
+
+    async recover(opened) {
+        const stored = this.state.active;
+        const turns = opened?.turns || [];
+        if (!stored) {
+            const inProgress = turns.findLast((turn) => turn?.status === 'inProgress');
+            if (inProgress) {
+                throw new Error('Codex thread has an unrelated in-progress turn');
+            }
+            return;
+        }
+        if (stored.messages.every((message) => this.state.has(message))) {
+            const abandoned = this.active;
+            this.active = null;
+            await abandoned?.lease.clear();
+            await this.state.setActive(null);
+            return;
+        }
+        const turn = stored.turnId
+            ? turns.find((item) => item?.id === stored.turnId)
+            : turns.findLast((item) => turnContainsMessage(
+                  item,
+                  stored.messages[0].messageId
+              ));
+        if (!turn) {
+            const abandoned = this.active;
+            this.active = null;
+            await abandoned?.lease.clear();
+            await this.state.setActive(null);
+            this.requeue(abandoned?.messages);
+            return;
+        }
+        const acceptedIds = new Set(turn.inputIds || []);
+        const currentMessages = this.active?.messages || [];
+        const omittedMessages = currentMessages.filter((message) => (
+            !acceptedIds.has(message.messageId)
+        ));
+        const messages = stored.messages
+            .filter((message) => acceptedIds.has(message.messageId))
+            .map((message) => (
+                currentMessages.find((current) => sameMessage(current, message))
+                || { ...message }
+            ));
+        if (!messages.length) {
+            const abandoned = this.active;
+            this.active = null;
+            await abandoned?.lease.clear();
+            await this.state.setActive(null);
+            this.requeue(abandoned?.messages);
+            return;
+        }
+        const reusableLease = this.active?.lease?.compositionId
+            === stored.compositionId
+            ? this.active.lease
+            : null;
+        const lease = reusableLease || await this.channel.beginWriting(
+            messages.at(-1),
+            stored.compositionId
+        );
+        this.active = {
+            turnId: turn.id,
+            lease,
+            responseCid: stored.responseCid,
+            responseCidPersisted: !!stored.responseCid,
+            messages,
+            reconcileNeeded: false,
+        };
+        await this.persistActive();
+        this.requeue(omittedMessages);
+        if (turn.status === 'inProgress') return;
+        await this.finish({
+            turnId: turn.id,
+            status: turn.status,
+            error: turn.error,
+            finalText: turn.finalText,
+        });
+    }
+
+    async run() {
+        this.unsubscribe = this.agent.subscribe((event) => (
+            this.handleAgentEvent(event)
+        ));
+        const opened = await this.openAgent();
+        const threadId = opened.threadId;
+        await this.state.setThreadId(threadId);
+        await this.recover(opened);
+        this.log('connector.ready', { threadId });
+        return this.channel.listen((prepared) => this.route(prepared));
+    }
+
+    async close() {
+        if (this.closing) return;
+        this.closing = true;
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        await Promise.allSettled([
+            this.channel.close(),
+            this.agent.close(),
+        ]);
+        await Promise.allSettled([
+            this.eventChain,
+            this.completion,
+            this.requeueChain,
+        ]);
+    }
+}
+
+export function createAgentConnector(options = {}) {
+    return new AgentConnector(options);
+}