@glyphteck/veyl 0.67.0 → 0.68.0

package/examples/codex-agent/index.js

@@ -0,0 +1,140 @@
+import process from 'node:process';
+import {
+    cleanProfileName,
+    defaultHomeDir,
+} from '@glyphteck/veyl';
+import { VEYL_AGENT_INSTRUCTIONS } from './agent-instructions.js';
+import { openAgentState } from './agent-state.js';
+import { createCodexAppServer } from './codex-app-server.js';
+import { codexModelConfig } from './codex-config.js';
+import {
+    codexInputForVeylMessage,
+    defaultVeylCliCommand,
+} from './codex-input.js';
+import { createAgentConnector } from './connector.js';
+import {
+    acquireConnectorInstance,
+    codexAgentPaths,
+} from './instance-lock.js';
+import { openVeylAgentChannel } from './veyl-channel.js';
+
+function cleanText(value) {
+    return String(value ?? '').trim();
+}
+
+function log(event, details = {}) {
+    const suffix = Object.keys(details).length
+        ? ` ${JSON.stringify(details)}`
+        : '';
+    process.stdout.write(`${new Date().toISOString()} ${event}${suffix}\n`);
+}
+
+const profile = cleanProfileName(process.env.VEYL_PROFILE, '');
+const owner = cleanText(process.env.VEYL_OWNER);
+const network = cleanText(process.env.VEYL_NETWORK).toUpperCase() || 'REGTEST';
+const sessionName = cleanProfileName(process.env.VEYL_SESSION, 'codex');
+const homeDir = cleanText(process.env.VEYL_HOME) || defaultHomeDir();
+const cwd = cleanText(process.env.CODEX_CWD) || process.cwd();
+const veylCli = cleanText(process.env.VEYL_CLI) || defaultVeylCliCommand();
+const { model, effort } = codexModelConfig(process.env);
+
+if (!profile || !owner) {
+    throw new Error('VEYL_PROFILE and VEYL_OWNER are required');
+}
+
+const paths = codexAgentPaths({
+    homeDir,
+    profile,
+    statePath: cleanText(process.env.VEYL_AGENT_STATE),
+});
+const instance = await acquireConnectorInstance({
+    paths,
+    profile,
+});
+
+let channel = null;
+let agent = null;
+let connector = null;
+let stopTask = null;
+function stop(signal) {
+    if (stopTask) return stopTask;
+    stopTask = (async () => {
+        log('connector.stopping', { signal });
+        if (connector) {
+            await connector.close();
+            return;
+        }
+        await Promise.allSettled([
+            channel?.close(),
+            agent?.close(),
+        ]);
+    })();
+    return stopTask;
+}
+
+try {
+    const state = await openAgentState({
+        path: paths.statePath,
+        binding: `${profile}\n${network}\n${owner.toLowerCase()}`,
+    });
+    const configuredThreadId = cleanText(process.env.VEYL_CODEX_THREAD_ID);
+    if (
+        configuredThreadId
+        && state.threadId
+        && configuredThreadId !== state.threadId
+    ) {
+        throw new Error('VEYL_CODEX_THREAD_ID does not match the connector state');
+    }
+
+    channel = await openVeylAgentChannel({
+        state,
+        owner,
+        profile,
+        username: cleanText(process.env.VEYL_USERNAME) || profile,
+        network,
+        homeDir,
+        temporaryRoot: paths.temporaryRoot,
+        temporaryOwner: instance,
+        sessionName,
+        log,
+    });
+    agent = createCodexAppServer({
+        codexPath: cleanText(process.env.CODEX_PATH) || 'codex',
+        threadId: configuredThreadId || state.threadId,
+        cwd,
+        model,
+        effort,
+        developerInstructions: VEYL_AGENT_INSTRUCTIONS,
+        replaceMissingThread: state.canReplaceThread,
+        serviceName: 'veyl_codex_agent',
+    });
+    connector = createAgentConnector({
+        state,
+        channel,
+        agent,
+        log,
+        inputForMessage: (message, options) => codexInputForVeylMessage(
+            message,
+            {
+                ...options,
+                cli: veylCli,
+                profile,
+                session: sessionName,
+            }
+        ),
+    });
+    process.once('SIGINT', () => void stop('SIGINT'));
+    process.once('SIGTERM', () => void stop('SIGTERM'));
+    log('connector.starting', {
+        profile,
+        owner,
+        network,
+        model,
+        effort,
+        threadId: configuredThreadId || state.threadId || 'new',
+    });
+    await connector.run();
+} finally {
+    await stop('runtime-ended');
+    await instance.release();
+}

package/examples/codex-agent/instance-lock.js

@@ -0,0 +1,359 @@
+import { randomUUID } from 'node:crypto';
+import {
+    lstat,
+    mkdir,
+    open,
+    readFile,
+    realpath,
+    rename,
+    rmdir,
+    unlink,
+} from 'node:fs/promises';
+import { hostname } from 'node:os';
+import {
+    basename,
+    dirname,
+    isAbsolute,
+    join,
+    relative,
+    resolve,
+    sep,
+} from 'node:path';
+import process from 'node:process';
+
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+const OWNER_FILE = 'owner.json';
+
+function cleanText(value) {
+    return String(value ?? '').trim();
+}
+
+function cleanProfile(value) {
+    const profile = cleanText(value).toLowerCase();
+    if (!/^[a-z0-9][a-z0-9._-]{0,63}$/u.test(profile)) {
+        throw new Error('connector profile must be filename-safe');
+    }
+    return profile;
+}
+
+function processIsRunning(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (error) {
+        return error?.code === 'EPERM';
+    }
+}
+
+function assertOwner(details, label) {
+    const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+    if (uid != null && details.uid !== uid) {
+        throw new Error(`${label} must belong to the current user`);
+    }
+}
+
+function assertMode(details, mode, label) {
+    if ((details.mode & 0o777) !== mode) {
+        throw new Error(`${label} must use ${mode.toString(8)} permissions`);
+    }
+}
+
+async function privateDirectory(path) {
+    await mkdir(path, { recursive: true, mode: DIR_MODE });
+    const details = await lstat(path);
+    if (!details.isDirectory() || details.isSymbolicLink()) {
+        throw new Error(`connector directory must be owner-only (0700): ${path}`);
+    }
+    assertOwner(details, 'connector directory');
+    assertMode(details, DIR_MODE, 'connector directory');
+}
+
+async function readClaim(path) {
+    let details;
+    try {
+        details = await lstat(path);
+    } catch (error) {
+        if (error?.code === 'ENOENT') return null;
+        throw error;
+    }
+    if (!details.isFile() || details.isSymbolicLink()) {
+        throw new Error('connector lock claim must be a private regular file');
+    }
+    assertOwner(details, 'connector lock claim');
+    assertMode(details, FILE_MODE, 'connector lock claim');
+
+    let value;
+    try {
+        value = JSON.parse(await readFile(path, 'utf8'));
+    } catch (error) {
+        if (error?.code === 'ENOENT') return null;
+        if (error instanceof SyntaxError) {
+            throw new Error('connector lock claim is invalid', { cause: error });
+        }
+        throw error;
+    }
+    const claim = {
+        version: Number(value?.version),
+        host: cleanText(value?.host),
+        pid: Number(value?.pid),
+        profile: cleanText(value?.profile),
+        statePath: cleanText(value?.statePath),
+        status: cleanText(value?.status),
+        token: cleanText(value?.token),
+    };
+    if (
+        claim.version !== 1
+        || !claim.token
+        || !claim.host
+        || !Number.isSafeInteger(claim.pid)
+        || claim.pid <= 0
+        || !claim.profile
+        || !claim.statePath
+        || claim.status !== 'held'
+    ) {
+        throw new Error('connector lock claim is invalid');
+    }
+    return claim;
+}
+
+async function inspectLockDirectory(path) {
+    let details;
+    try {
+        details = await lstat(path);
+    } catch (error) {
+        if (error?.code === 'ENOENT') return null;
+        throw error;
+    }
+    if (!details.isDirectory() || details.isSymbolicLink()) {
+        throw new Error('connector lock must be a private directory');
+    }
+    assertOwner(details, 'connector lock');
+    assertMode(details, DIR_MODE, 'connector lock');
+    const claim = await readClaim(join(path, OWNER_FILE));
+    if (!claim) throw new Error('connector lock claim is missing');
+    return claim;
+}
+
+async function removeClaimDirectory(path) {
+    await unlink(join(path, OWNER_FILE)).catch((error) => {
+        if (error?.code !== 'ENOENT') throw error;
+    });
+    await rmdir(path).catch((error) => {
+        if (error?.code !== 'ENOENT') throw error;
+    });
+}
+
+function containsPath(parent, candidate) {
+    const child = relative(parent.toLowerCase(), candidate.toLowerCase());
+    return child === ''
+        || (!isAbsolute(child) && child !== '..' && !child.startsWith(`..${sep}`));
+}
+
+async function canonicalFuturePath(path) {
+    const suffix = [];
+    let cursor = resolve(path);
+    while (true) {
+        try {
+            return resolve(await realpath(cursor), ...suffix);
+        } catch (error) {
+            if (error?.code !== 'ENOENT') throw error;
+            const parent = dirname(cursor);
+            if (parent === cursor) throw error;
+            suffix.unshift(basename(cursor));
+            cursor = parent;
+        }
+    }
+}
+
+async function validateExplicitStatePath(paths) {
+    if (!paths.explicitStatePath) return;
+    const [root, statePath] = await Promise.all([
+        canonicalFuturePath(paths.root),
+        canonicalFuturePath(paths.statePath),
+    ]);
+    if (
+        containsPath(join(root, 'tmp'), statePath)
+        || containsPath(join(root, 'instance.lock'), statePath)
+        || statePath.toLowerCase() === root.toLowerCase()
+    ) {
+        throw new Error('agent state path overlaps reserved connector storage');
+    }
+}
+
+export function codexAgentPaths(options = {}) {
+    const homeDir = resolve(cleanText(options.homeDir));
+    const profile = cleanProfile(options.profile);
+    const root = join(homeDir, 'agents', `${profile}.codex`);
+    const explicitStatePath = cleanText(options.statePath);
+    const statePath = resolve(explicitStatePath || join(root, 'state.json'));
+    const temporaryRoot = join(root, 'tmp');
+    const lockPath = join(root, 'instance.lock');
+    if (
+        statePath === root
+        || containsPath(temporaryRoot, statePath)
+        || containsPath(lockPath, statePath)
+    ) {
+        throw new Error('agent state path overlaps reserved connector storage');
+    }
+    return Object.freeze({
+        root,
+        statePath,
+        temporaryRoot,
+        lockPath,
+        explicitStatePath: !!explicitStatePath,
+    });
+}
+
+export class ConnectorInstanceLock {
+    constructor(options = {}) {
+        if (!options.paths?.root || !options.paths?.lockPath) {
+            throw new Error('connector paths required');
+        }
+        this.paths = options.paths;
+        this.profile = cleanProfile(options.profile);
+        this.host = cleanText(options.host) || hostname();
+        this.pid = Number(options.pid) || process.pid;
+        this.running = options.processIsRunning || processIsRunning;
+        this.token = null;
+        this.claimPath = null;
+        this.claim = null;
+    }
+
+    async createCandidate() {
+        const token = randomUUID();
+        const path = join(this.paths.root, `.instance-claim-${token}`);
+        const claimPath = join(path, OWNER_FILE);
+        const claim = {
+            version: 1,
+            token,
+            host: this.host,
+            pid: this.pid,
+            profile: this.profile,
+            statePath: this.paths.statePath,
+            status: 'held',
+            startedAt: Date.now(),
+        };
+        await mkdir(path, { mode: DIR_MODE });
+        let handle;
+        try {
+            handle = await open(claimPath, 'wx', FILE_MODE);
+            await handle.writeFile(`${JSON.stringify(claim, null, 2)}\n`);
+            await handle.sync();
+        } catch (error) {
+            await handle?.close().catch(() => {});
+            await removeClaimDirectory(path).catch(() => {});
+            throw error;
+        }
+        await handle.close();
+        return { claim, path };
+    }
+
+    async installCandidate(candidate) {
+        try {
+            await rename(candidate.path, this.paths.lockPath);
+            return true;
+        } catch (error) {
+            if (
+                error?.code === 'EEXIST'
+                || error?.code === 'ENOTEMPTY'
+            ) {
+                return false;
+            }
+            throw error;
+        }
+    }
+
+    async rejectOrReclaimExisting() {
+        const claim = await inspectLockDirectory(this.paths.lockPath);
+        if (!claim) return;
+        if (claim.host !== this.host || this.running(claim.pid)) {
+            const error = new Error(
+                `Veyl Codex connector already running (${claim.host} pid ${claim.pid})`
+            );
+            error.code = 'veyl_codex_connector_running';
+            throw error;
+        }
+
+        const quarantine = `${this.paths.lockPath}.stale-${claim.token}`;
+        try {
+            await rename(this.paths.lockPath, quarantine);
+        } catch (error) {
+            if (
+                error?.code === 'ENOENT'
+                || error?.code === 'EEXIST'
+                || error?.code === 'ENOTEMPTY'
+            ) {
+                return;
+            }
+            throw error;
+        }
+    }
+
+    async acquire() {
+        if (this.token) return this;
+        await validateExplicitStatePath(this.paths);
+        await privateDirectory(this.paths.root);
+        if (this.paths.explicitStatePath) {
+            await privateDirectory(dirname(this.paths.statePath));
+        }
+
+        const candidate = await this.createCandidate();
+        try {
+            while (!await this.installCandidate(candidate)) {
+                await this.rejectOrReclaimExisting();
+            }
+            this.token = candidate.claim.token;
+            this.claimPath = join(this.paths.lockPath, OWNER_FILE);
+            this.claim = candidate.claim;
+            return this;
+        } catch (error) {
+            await removeClaimDirectory(candidate.path).catch(() => {});
+            throw error;
+        }
+    }
+
+    async owns() {
+        if (!this.token || !this.claimPath) return false;
+        try {
+            const claim = await inspectLockDirectory(this.paths.lockPath);
+            return claim?.token === this.token
+                && claim.host === this.host
+                && claim.pid === this.pid
+                && claim.profile === this.profile
+                && claim.statePath === this.paths.statePath;
+        } catch {
+            return false;
+        }
+    }
+
+    async assertHeld() {
+        if (!await this.owns()) {
+            throw new Error('Veyl Codex connector lock is no longer held');
+        }
+    }
+
+    async release() {
+        const token = this.token;
+        if (!token || !this.claimPath) return false;
+        const claim = await inspectLockDirectory(this.paths.lockPath);
+        if (claim?.token !== token) {
+            throw new Error('Veyl Codex connector lock changed');
+        }
+
+        const released = `${this.paths.lockPath}.released-${token}`;
+        await rename(this.paths.lockPath, released);
+        this.token = null;
+        this.claimPath = null;
+        this.claim = null;
+        await removeClaimDirectory(released);
+        return true;
+    }
+}
+
+export async function acquireConnectorInstance(options = {}) {
+    const lock = new ConnectorInstanceLock(options);
+    await lock.acquire();
+    return lock;
+}

package/examples/codex-agent/readme.md

@@ -0,0 +1,88 @@
+# single-account Codex agent
+
+This example runs one ordinary Veyl account continuously and connects its owner-only direct chat to one Codex app-server thread. It uses the Codex installation's existing ChatGPT authentication. It does not read, require, or store an OpenAI API key.
+
+Veyl encryption ends at this local agent account. Accepted owner plaintext and decrypted attachments are passed to the configured Codex/OpenAI account, so that account's data controls and retention apply.
+
+The Veyl side is harness-neutral:
+
+- `veyl-channel.js` owns account boot, the inbound allowlist, encrypted events, attachments, live presence, writing state, final delivery, and the persistent CLI socket.
+- `chat-whitelist.js` is the example-local owner identity check layered over Veyl's public admission policy.
+- `connector.js` owns turn routing, steering, retries, replay checkpoints, and crash reconciliation through a five-method agent contract.
+- `instance-lock.js` gives the exact local Veyl profile one connector owner, independent of its CLI session name, and safely reclaims dead-process claims.
+- `agent-state.js` stores only routing identifiers, the pinned public owner identity, and processed message ids in an owner-only file. It never stores decrypted message text.
+- `agent-instructions.js` exports the exact style and operational prompts separately, then combines them as thread-level Codex developer instructions on both creation and resume.
+- `codex-app-server.js` is the Codex-specific harness driver.
+- `codex-input.js` maps a Veyl message into Codex input items.
+- `index.js` is only configuration and composition.
+
+To adapt another harness, keep `agent-state.js`, `instance-lock.js`, `chat-whitelist.js`, `veyl-channel.js`, and `connector.js`, then replace `codex-app-server.js` plus `codex-input.js`. Veyl does not need a harness-specific backend, MCP action surface, or server-readable agent queue.
+
+## harness adapter contract
+
+The connector expects these five methods:
+
+- `open()` starts or reconnects the harness and returns `{ threadId, turns }`. The thread id must remain stable for the connector's lifetime and every reconnect. A harness that allocates ids before persisting an empty thread may return `{ replacedThreadId }` only when that exact empty id is missing; the connector accepts it only while local state has no active or processed owner messages. Each recovery turn is `{ id, status, error, inputIds, finalText }`. `status` is `inProgress`, `completed`, `failed`, or `interrupted`; `inputIds` contains the exact caller-supplied `clientUserMessageId` values, never harness-internal item ids.
+- `subscribe(listener)` returns an unsubscribe function. It emits `message.delta` as output streams, `turn.started` with `{ turnId }`, `turn.completed` with `{ turnId, status, error, inputIds, finalText }`, and `server.exit` with `{ expected }` when the harness transport stops. Completion `inputIds` are authoritative and let the connector requeue a steer whose transport outcome was uncertain.
+- `startTurn({ input, clientUserMessageId })` accepts a new turn and returns `{ turnId }`.
+- `steerTurn({ input, clientUserMessageId, expectedTurnId })` adds an input to that exact active turn.
+- `close()` stops the harness and resolves only after pending calls are rejected or settled.
+
+Error outcome is part of the contract. A normal rejected promise means the harness definitely did not accept that start or steer. If a timeout, disconnect, or process failure makes acceptance uncertain, the rejection must carry `error.outcomeUnknown === true`. The connector then reconciles through `open()` and the persisted client input ids instead of duplicating a possibly accepted action. `finalText` is delivered as a successful answer only when `status === 'completed'`; failed and interrupted turns get explicit failure responses. The connector and driver tests are executable conformance examples for these semantics.
+
+## setup
+
+Install the SDK and Codex CLI, then authenticate Codex once with your normal ChatGPT account:
+
+```bash
+npm install @glyphteck/veyl
+codex login
+```
+
+The Codex binary bundled with the ChatGPT macOS app also works; point `CODEX_PATH` at it if `codex` is not on `PATH`.
+
+Run the packaged example:
+
+```bash
+VEYL_PROFILE=my-agent \
+VEYL_USERNAME=myagent \
+VEYL_OWNER=@myaccount \
+VEYL_NETWORK=MAINNET \
+CODEX_CWD=/absolute/path/to/workspace \
+node node_modules/@glyphteck/veyl/examples/codex-agent/index.js
+```
+
+On its first run, the process creates the Veyl account and vault and saves both generated keys in the normal owner-only Veyl profile. Account creation records the current Veyl Terms acceptance in the same creation transaction; there is no separate human click. Later runs authenticate and unlock the saved profile. Connector state, its process lock, and temporary attachment root live under `~/.veyl/agents/<profile>.codex/`, whose owner-only permissions are checked before use.
+
+Omit `VEYL_USERNAME` after creation. `VEYL_PROFILE` and `VEYL_OWNER` remain required. The default network is `REGTEST`; set `MAINNET` for a real account. Network selects the self-custodial wallet network, not a privileged chat environment.
+
+`VEYL_CODEX_THREAD_ID` is optional. Without it, the connector creates a dedicated Codex thread on first run and remembers the returned id. Supplying it resumes an existing thread. The Veyl-prefixed name deliberately avoids inheriting the id of a Codex task that launches the connector. The example defaults to `gpt-5.6-luna` with `low` reasoning for a fast, economical always-on chat agent. `CODEX_MODEL` and `CODEX_REASONING` can override those explicit defaults.
+
+Useful optional variables:
+
+| variable | purpose |
+| --- | --- |
+| `CODEX_PATH` | Codex executable; defaults to `codex` |
+| `VEYL_CODEX_THREAD_ID` | existing task to resume instead of creating one |
+| `CODEX_MODEL` | model override; defaults to `gpt-5.6-luna` |
+| `CODEX_REASONING` | reasoning-effort override; defaults to `low` |
+| `VEYL_HOME` | Veyl profile root; defaults to `~/.veyl` |
+| `VEYL_SESSION` | owner-only persistent CLI socket name; defaults to `codex` |
+| `VEYL_AGENT_STATE` | explicit connector-state path; its parent must be owner-only (`0700`) |
+| `VEYL_CLI` | command prefix shown to Codex; defaults to this package's absolute `dist/cli.js` through the current Node executable |
+
+Use a process supervisor appropriate to the host. The process handles `SIGINT` and `SIGTERM`, clears writing state, leaves live rooms, closes the CLI socket, locks the vault, and shuts down Codex cleanly. A profile-scoped instance lock is acquired before connector state, temporary attachments, or the account runtime can be changed. A second launch fails without disturbing the running process, even if it chooses a different `VEYL_SESSION`; after a crash, its dead process claim is reclaimed automatically.
+
+## chat and safety behavior
+
+The configured owner is allowed by username only during first resolution. The connector then pins the owner's stable Veyl uid and chat public key and publishes `direct: closed`, `groups: closed`, plus one opaque direct grant for that owner. Closed accounts disappear from other clients' new-chat and group-invite choices, while the private pair capability still lets the owner start the direct chat. The fixed-size public grant set does not reveal which account is allowed.
+
+Veyl's existing blocklist remains authoritative and is checked first. Blocking the owner therefore rejects the chat even though the owner has a grant. The local identity check then admits only a signed/decrypted two-member direct Welcome from the pinned owner; groups and every other sender fail closed before owner-row persistence. Existing established chats and chats this account starts outbound are not invalidated by the admission policy, but this example's event loop responds only to the pinned owner.
+
+For each accepted owner message, the process enters the ordinary encrypted live room and stays present for the process lifetime. It publishes a stable composition id while Codex streams, renews the writing lease, stops typing at completion, and sends the durable final with the same composition id so the temporary writing row becomes the final response in place.
+
+The same unlocked client owns an owner-only persistent CLI socket. Codex can use the complete public CLI for chat history, files, reactions, profile actions, and explicitly authorized wallet work without starting a second Veyl runtime. The connector itself delivers the final response, so the prompt tells Codex not to duplicate that message through the CLI.
+
+Incoming messages are checkpointed only after the final Veyl send succeeds. The connector persists active input ids before every start or steer. Once a turn completes, it allocates the response cid at send time and persists it before the first delivery attempt, keeping the final below every follow-up it answers while making an ambiguous send exactly reconcilable after restart. Completed Codex output is recovered from the remembered thread and delivered with that same persisted cid. State, lock claims, and temporary files live under the profile's dedicated owner-only connector directory. Temporary decrypted attachment files are mode `0600` and only the active lock holder may remove them after the turn or shutdown.
+
+The example sets `approvalPolicy: never` and `dangerFullAccess` because an independent local Codex agent must reach both its workspace and the owner-only Veyl CLI socket. Run it only on a host and workspace you trust. The driver explicitly declines approval and elicitation requests and fails closed on every server request it does not handle.