@glyphteck/veyl 0.66.3 → 0.68.0

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

@@ -0,0 +1,357 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import {
+    chmod,
+    lstat,
+    mkdir,
+    open,
+    rename,
+    unlink,
+    writeFile,
+} from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+export const AGENT_STATE_VERSION = 1;
+
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+const MAX_PROCESSED_MESSAGES = 2_000;
+
+function cleanText(value) {
+    return String(value ?? '').trim();
+}
+
+function cleanBinding(value) {
+    const binding = cleanText(value);
+    if (!binding) throw new Error('agent state binding required');
+    return binding;
+}
+
+function cleanIdentity(value) {
+    if (value == null) return null;
+    const uid = cleanText(value.uid);
+    const chatPK = cleanText(value.chatPK).toLowerCase();
+    if (!uid || !/^[0-9a-f]{64}$/u.test(chatPK)) {
+        throw new Error('invalid pinned owner identity');
+    }
+    return Object.freeze({ uid, chatPK });
+}
+
+function cleanProcessed(values) {
+    if (!Array.isArray(values)) throw new Error('invalid processed messages');
+    return [...new Set(values.map(cleanText).filter(Boolean))]
+        .slice(-MAX_PROCESSED_MESSAGES);
+}
+
+function eventCoordinates(event) {
+    const chatId = cleanText(
+        event?.chatId || event?.message?.chatId || event?.chat?.id
+    )
+        .toLowerCase();
+    const messageId = cleanText(
+        event?.messageId || event?.message?.id || event?.message?.cid
+    );
+    return chatId && messageId ? `${chatId}:${messageId}` : '';
+}
+
+function cleanActive(value) {
+    if (value == null) return null;
+    const compositionId = cleanText(value.compositionId).toLowerCase();
+    const responseCid = value.responseCid == null
+        ? null
+        : cleanText(value.responseCid).toLowerCase();
+    const turnId = cleanText(value.turnId) || null;
+    const messages = Array.isArray(value.messages)
+        ? value.messages.map((message) => ({
+              chatId: cleanText(message?.chatId).toLowerCase(),
+              messageId: cleanText(message?.messageId),
+          }))
+        : [];
+    if (
+        !/^[0-9a-f]{32}$/u.test(compositionId)
+        || (
+            responseCid !== null
+            && (
+                responseCid.length <= 6
+                || !/^[0-9a-z]+[0-9a-f]{6}$/u.test(responseCid)
+                || !Number.isFinite(Number.parseInt(responseCid.slice(0, -6), 36))
+            )
+        )
+        || !messages.length
+        || messages.some((message) => (
+            !/^[0-9a-f]{64}$/u.test(message.chatId) || !message.messageId
+        ))
+        || messages.some((message) => message.chatId !== messages[0].chatId)
+    ) {
+        throw new Error('invalid active agent turn');
+    }
+    return {
+        turnId,
+        compositionId,
+        responseCid,
+        messages,
+    };
+}
+
+function currentUid() {
+    return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+
+function assertOwned(stats, label) {
+    const uid = currentUid();
+    if (uid !== null && stats.uid !== uid) {
+        throw new Error(`${label} must be owned by the current user`);
+    }
+}
+
+function assertMode(stats, expected, label) {
+    if ((stats.mode & 0o777) !== expected) {
+        throw new Error(
+            `${label} must use ${expected.toString(8)} permissions`
+        );
+    }
+}
+
+async function ensurePrivateDirectory(path) {
+    await mkdir(path, { recursive: true, mode: DIR_MODE });
+    const stats = await lstat(path);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error('agent state parent must be a private directory');
+    }
+    assertOwned(stats, 'agent state parent');
+    assertMode(stats, DIR_MODE, 'agent state parent');
+}
+
+async function privateFileStats(path, options = {}) {
+    let stats;
+    try {
+        stats = await lstat(path);
+    } catch (error) {
+        if (options.allowMissing === true && error?.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+        throw new Error('agent state must be a private regular file');
+    }
+    assertOwned(stats, 'agent state');
+    assertMode(stats, FILE_MODE, 'agent state');
+    return stats;
+}
+
+async function readPrivateFile(path) {
+    if (!await privateFileStats(path, { allowMissing: true })) return null;
+    const noFollow = constants.O_NOFOLLOW || 0;
+    const handle = await open(path, constants.O_RDONLY | noFollow);
+    try {
+        const stats = await handle.stat();
+        if (!stats.isFile()) {
+            throw new Error('agent state must be a private regular file');
+        }
+        assertOwned(stats, 'agent state');
+        assertMode(stats, FILE_MODE, 'agent state');
+        return await handle.readFile('utf8');
+    } finally {
+        await handle.close();
+    }
+}
+
+function stateDocument(binding, value = {}) {
+    return {
+        version: AGENT_STATE_VERSION,
+        binding,
+        initialized: value.initialized === true,
+        owner: cleanIdentity(value.owner),
+        threadId: cleanText(value.threadId) || null,
+        active: cleanActive(value.active),
+        processed: cleanProcessed(value.processed || []),
+    };
+}
+
+export class AgentState {
+    constructor(path, value) {
+        this.path = resolve(path);
+        this.value = value;
+        this.processed = new Set(value.processed);
+        this.mutation = Promise.resolve();
+    }
+
+    get initialized() {
+        return this.value.initialized;
+    }
+
+    get owner() {
+        return this.value.owner;
+    }
+
+    get threadId() {
+        return this.value.threadId;
+    }
+
+    get active() {
+        return this.value.active;
+    }
+
+    get canReplaceThread() {
+        return !!this.value.threadId
+            && this.value.active === null
+            && this.processed.size === 0;
+    }
+
+    has(event) {
+        const key = eventCoordinates(event);
+        return !!key && this.processed.has(key);
+    }
+
+    hasChat(chat) {
+        const chatId = cleanText(chat?.id || chat).toLowerCase();
+        return !!chatId && this.value.processed.some((key) => (
+            key.startsWith(`${chatId}:`)
+        ));
+    }
+
+    update(operation) {
+        const task = this.mutation.then(async () => {
+            const previousValue = stateDocument(
+                this.value.binding,
+                this.value
+            );
+            const previousProcessed = new Set(this.processed);
+            try {
+                operation();
+                await this.persist();
+            } catch (error) {
+                this.value = previousValue;
+                this.processed = previousProcessed;
+                throw error;
+            }
+        });
+        this.mutation = task.catch(() => {});
+        return task;
+    }
+
+    setInitialized() {
+        if (this.value.initialized) return this.mutation;
+        return this.update(() => {
+            this.value.initialized = true;
+        });
+    }
+
+    pinOwner(owner) {
+        const identity = cleanIdentity(owner);
+        if (
+            this.value.owner
+            && (
+                this.value.owner.uid !== identity.uid
+                || this.value.owner.chatPK !== identity.chatPK
+            )
+        ) {
+            throw new Error('configured owner no longer matches the pinned identity');
+        }
+        if (this.value.owner) return this.mutation;
+        return this.update(() => {
+            this.value.owner = identity;
+        });
+    }
+
+    setThreadId(threadId) {
+        const id = cleanText(threadId);
+        if (!id) throw new Error('Codex thread id required');
+        if (this.value.threadId === id) return this.mutation;
+        return this.update(() => {
+            this.value.threadId = id;
+        });
+    }
+
+    replaceThreadId(previousThreadId, nextThreadId) {
+        const previous = cleanText(previousThreadId);
+        const next = cleanText(nextThreadId);
+        if (!previous || !next || previous === next) {
+            throw new Error('valid replacement Codex thread ids required');
+        }
+        if (
+            this.value.threadId !== previous
+            || this.value.active !== null
+            || this.processed.size !== 0
+        ) {
+            throw new Error('only a pristine missing Codex thread can be replaced');
+        }
+        return this.update(() => {
+            this.value.threadId = next;
+        });
+    }
+
+    setActive(active) {
+        const next = cleanActive(active);
+        return this.update(() => {
+            this.value.active = next;
+        });
+    }
+
+    mark(events) {
+        const list = Array.isArray(events) ? events : [events];
+        const keys = list.map(eventCoordinates).filter(Boolean);
+        if (!keys.length) return this.mutation;
+        return this.update(() => {
+            for (const key of keys) {
+                this.processed.delete(key);
+                this.processed.add(key);
+            }
+            this.value.processed = [...this.processed]
+                .slice(-MAX_PROCESSED_MESSAGES);
+            this.processed = new Set(this.value.processed);
+        });
+    }
+
+    complete(events) {
+        const list = Array.isArray(events) ? events : [events];
+        const keys = list.map(eventCoordinates).filter(Boolean);
+        if (!keys.length) throw new Error('completed agent turn requires messages');
+        return this.update(() => {
+            for (const key of keys) {
+                this.processed.delete(key);
+                this.processed.add(key);
+            }
+            this.value.processed = [...this.processed]
+                .slice(-MAX_PROCESSED_MESSAGES);
+            this.processed = new Set(this.value.processed);
+            this.value.active = null;
+        });
+    }
+
+    async persist() {
+        const parent = dirname(this.path);
+        await ensurePrivateDirectory(parent);
+        await privateFileStats(this.path, { allowMissing: true });
+        const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+        let installed = false;
+        try {
+            await writeFile(
+                temporary,
+                `${JSON.stringify(this.value, null, 2)}\n`,
+                { mode: FILE_MODE, flag: 'wx' }
+            );
+            await chmod(temporary, FILE_MODE);
+            await rename(temporary, this.path);
+            installed = true;
+        } finally {
+            if (!installed) await unlink(temporary).catch(() => {});
+        }
+    }
+}
+
+export async function openAgentState(options = {}) {
+    const path = resolve(options.path || 'codex-agent-state.json');
+    const binding = cleanBinding(options.binding);
+    await ensurePrivateDirectory(dirname(path));
+    const serialized = await readPrivateFile(path);
+    const stored = serialized === null ? null : JSON.parse(serialized);
+    if (stored && stored.version !== AGENT_STATE_VERSION) {
+        throw new Error('unsupported agent state version');
+    }
+    if (stored && cleanBinding(stored.binding) !== binding) {
+        throw new Error('agent state belongs to a different connector');
+    }
+    return new AgentState(path, stateDocument(binding, stored || {}));
+}

package/examples/codex-agent/chat-whitelist.js

@@ -0,0 +1,104 @@
+const CHAT_PK_RE = /^[0-9a-f]{64}$/iu;
+const USERNAME_RE = /^[a-z0-9]{1,12}$/u;
+const ACCEPT = 'accept';
+const REJECT = 'reject';
+
+function cleanText(value) {
+    return String(value ?? '').trim();
+}
+
+function cleanUsername(value) {
+    const username = cleanText(value).replace(/^@+/u, '').toLowerCase();
+    if (!USERNAME_RE.test(username)) {
+        throw new Error('valid whitelist username required');
+    }
+    return username;
+}
+
+function cleanChatPK(value) {
+    const chatPK = cleanText(value).toLowerCase();
+    if (!CHAT_PK_RE.test(chatPK)) {
+        throw new Error('valid whitelist chat key required');
+    }
+    return chatPK;
+}
+
+function cleanUid(value) {
+    const uid = cleanText(value);
+    if (!uid) throw new Error('valid whitelist uid required');
+    return uid;
+}
+
+function whitelistIdentity(value) {
+    if (typeof value === 'string') {
+        const peer = cleanText(value);
+        if (!peer) throw new Error('whitelist peer required');
+        return CHAT_PK_RE.test(peer)
+            ? Object.freeze({ chatPK: cleanChatPK(peer) })
+            : Object.freeze({ username: cleanUsername(peer) });
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('whitelist peer must be a username, chat key, or identity');
+    }
+    const identity = {};
+    if (Object.hasOwn(value, 'uid')) identity.uid = cleanUid(value.uid);
+    if (Object.hasOwn(value, 'chatPK')) identity.chatPK = cleanChatPK(value.chatPK);
+    if (Object.hasOwn(value, 'username')) {
+        identity.username = cleanUsername(value.username);
+    }
+    if (!Object.keys(identity).length) {
+        throw new Error('whitelist identity requires uid, chatPK, or username');
+    }
+    return Object.freeze(identity);
+}
+
+function sameIdentity(member, sender) {
+    const uid = cleanText(member?.uid);
+    const chatPK = cleanText(member?.chatPK).toLowerCase();
+    const chatSigningPK = cleanText(member?.chatSigningPK).toLowerCase();
+    const notificationPK = cleanText(member?.notificationPK).toLowerCase();
+    return !!uid
+        && CHAT_PK_RE.test(chatPK)
+        && CHAT_PK_RE.test(chatSigningPK)
+        && CHAT_PK_RE.test(notificationPK)
+        && uid === cleanText(sender?.uid)
+        && chatPK === cleanText(sender?.chatPK).toLowerCase()
+        && chatSigningPK === cleanText(sender?.chatSigningPK).toLowerCase()
+        && notificationPK === cleanText(sender?.notificationPK).toLowerCase();
+}
+
+function matchesAllowedPeer(peer, sender) {
+    return (peer.uid == null || peer.uid === cleanText(sender?.uid))
+        && (
+            peer.chatPK == null
+            || peer.chatPK === cleanText(sender?.chatPK).toLowerCase()
+        )
+        && (
+            peer.username == null
+            || peer.username === cleanText(sender?.username).toLowerCase()
+        );
+}
+
+export function createChatWhitelist(peers) {
+    if (!Array.isArray(peers)) throw new Error('chat whitelist must be an array');
+    const allowed = Object.freeze(peers.map(whitelistIdentity));
+    return (context) => {
+        if (context?.chat?.lineage !== 'direct') return REJECT;
+        const members = context?.chat?.members;
+        if (!Array.isArray(members) || members.length !== 2) return REJECT;
+
+        const selfUid = cleanText(context?.self?.uid);
+        const selfChatPK = cleanText(context?.self?.chatPK).toLowerCase();
+        if (!selfUid || !CHAT_PK_RE.test(selfChatPK)) return REJECT;
+        const self = members.filter((member) => (
+            cleanText(member?.uid) === selfUid
+            && cleanText(member?.chatPK).toLowerCase() === selfChatPK
+        ));
+        if (self.length !== 1) return REJECT;
+        const remote = members.find((member) => member !== self[0]);
+        if (!sameIdentity(remote, context?.sender)) return REJECT;
+        return allowed.some((peer) => matchesAllowedPeer(peer, context.sender))
+            ? ACCEPT
+            : REJECT;
+    };
+}