@aopslabs/aops 0.3.20 → 0.3.21

package/dist/commands/chat-wake-watch.js

@@ -0,0 +1,369 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { Command } from 'commander';
+import { wakeAgentSession } from '@aopslabs/aops-agent-runtime';
+import { Chatv3Client } from '@aopslabs/domain-product-client-chatv3';
+import { loadChatv3Session } from '../utils/chatv3-session-store.js';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MEMBER_TOKEN = /^cv3m_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})_[A-Za-z0-9_-]{16,}$/i;
+const MAX_CAPTURE = 4 * 1024 * 1024;
+const MEMBER_AUTH_REASONS = new Set([
+    'member_token_required',
+    'member_token_invalid_format',
+    'member_token_unknown',
+    'member_token_mismatch',
+    'membership_inactive',
+    'membership_channel_mismatch',
+]);
+const RECOVERABLE_MEMBER_AUTH_REASONS = new Set([
+    'member_token_unknown',
+    'member_token_mismatch',
+]);
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const required = (value, label) => {
+    const result = value?.trim();
+    if (!result)
+        throw new Error(`${label} is required.`);
+    return result;
+};
+function integer(value, fallback, label, min, max) {
+    if (value === undefined)
+        return fallback;
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < min || result > max)
+        throw new Error(`${label} must be between ${min} and ${max}.`);
+    return result;
+}
+export function resolveWakeWatchConfig(options, env = process.env) {
+    if (options.wakeApproved !== true)
+        throw new Error('--wake-approved is required; watcher startup refused.');
+    const chatSession = required(options.session, '--session');
+    const room = options.room?.trim() || 'general';
+    const targetSessionId = required(options.targetSessionId, '--target-session-id');
+    if (!UUID.test(targetSessionId))
+        throw new Error('--target-session-id must be a UUID.');
+    const watcherMemberId = required(options.watcherMemberId, '--watcher-member-id');
+    const targetMemberId = required(options.targetMemberId, '--target-member-id');
+    if (!UUID.test(watcherMemberId))
+        throw new Error('--watcher-member-id must be a UUID.');
+    if (!UUID.test(targetMemberId))
+        throw new Error('--target-member-id must be a UUID.');
+    const ignoredMemberIds = new Set((options.ignoreMember ?? []).map((entry) => entry.trim()).filter(Boolean));
+    if (!ignoredMemberIds.has(watcherMemberId))
+        throw new Error('ignore-set must contain --watcher-member-id; startup refused.');
+    if (!ignoredMemberIds.has(targetMemberId))
+        throw new Error('ignore-set must contain --target-member-id; startup refused.');
+    const targetSessionHash = createHash('sha256').update(targetSessionId).digest('hex').slice(0, 24);
+    const stateName = createHash('sha256').update(`${chatSession}:${room}:${targetSessionHash}`).digest('hex').slice(0, 24);
+    return {
+        chatSession, room, targetSessionId, watcherMemberId, targetMemberId, ignoredMemberIds, targetSessionHash,
+        once: options.once === true,
+        initialCursor: integer(options.afterSeq, 0, '--after-seq', 0, Number.MAX_SAFE_INTEGER),
+        statePath: path.resolve(options.statePath ?? path.join(homedir(), '.aops', 'chat-wake-watch', `${stateName}.json`)),
+        storePath: options.storePath?.trim() || undefined,
+        sessionOwner: options.sessionOwner?.trim() || env.AOPS_CHATV3_SESSION_OWNER?.trim() || `wake-watch-${chatSession}`,
+        apiBaseUrl: options.apiBaseUrl?.trim() || env.AOPS_API_BASE_URL?.trim() || 'http://127.0.0.1:5900',
+        listenTimeoutSec: integer(options.listenTimeoutSec, 30, '--listen-timeout-sec', 1, 300),
+        intervalSec: integer(options.intervalSec, 2, '--interval-sec', 1, 60),
+        maxBackoffMs: integer(options.maxBackoffMs, 30_000, '--max-backoff-ms', 1_000, 300_000),
+        maxConsecutiveFailures: integer(options.maxConsecutiveFailures, 10, '--max-consecutive-failures', 1, 100),
+    };
+}
+const verifyWakeWatchMember = async ({ serverBaseUrl, channelId, memberToken }) => {
+    const client = new Chatv3Client({ serverBaseUrl, memberToken });
+    await client.listMembers(channelId, { status: 'active', limit: 1 });
+};
+export async function preflightWakeWatchSession(config, verifyMember = verifyWakeWatchMember) {
+    const loaded = await loadChatv3Session(config.chatSession, {
+        storePath: config.storePath,
+        owner: config.sessionOwner,
+    });
+    const channelId = loaded.record.channel.id?.trim();
+    if (!channelId || !UUID.test(channelId))
+        throw new Error('watcher ChatV3 session has an invalid channel id; startup refused.');
+    const parsed = MEMBER_TOKEN.exec(loaded.secrets.memberToken);
+    if (!parsed)
+        throw new Error('watcher ChatV3 session has an invalid member token; startup refused.');
+    if (parsed[1].toLowerCase() !== config.watcherMemberId.toLowerCase()) {
+        throw new Error('watcher member id does not match the owner-isolated ChatV3 session token; startup refused.');
+    }
+    try {
+        await verifyMember({
+            serverBaseUrl: config.apiBaseUrl || loaded.record.serverBaseUrl,
+            channelId,
+            memberToken: loaded.secrets.memberToken,
+        });
+    }
+    catch {
+        throw new Error('watcher ChatV3 member admission failed; startup refused.');
+    }
+    return { ...config, verifiedChannelId: channelId };
+}
+export function normalizeWakeWatchMessages(payload, cursor) {
+    const result = record(payload) && record(payload.result) ? payload.result : null;
+    if (!result || !Array.isArray(result.messages))
+        throw new Error('chat listen result.messages is not an array.');
+    return result.messages
+        .filter((message) => record(message) && Number.isSafeInteger(message.seq) && message.seq > cursor && typeof message.senderMemberId === 'string')
+        .sort((left, right) => left.seq - right.seq);
+}
+export const wakeWatchIdempotencyKey = (channelId, roomId, seq, hash) => `${channelId}:${roomId}:${seq}:${hash}`;
+export function selectWakeWatchBatch(messages, config, state, channelId, roomId) {
+    const processed = new Set(state.processed);
+    const triggers = messages.filter((message) => !config.ignoredMemberIds.has(message.senderMemberId) && !processed.has(wakeWatchIdempotencyKey(channelId, roomId, message.seq, config.targetSessionHash)));
+    return { triggers, nextCursor: messages.at(-1)?.seq ?? state.cursor };
+}
+export function buildWakeWatchPrompt(config, channelId, roomId, triggers) {
+    const seqs = triggers.map((message) => message.seq);
+    const first = Math.min(...seqs);
+    const last = Math.max(...seqs);
+    return [
+        `AOPS ChatV3 channel=${channelId} room=${roomId} (${config.room}) icin yeni harici mesaj var.`,
+        `Tetikleyen seq araligi: ${first}-${last}; seq listesi: ${seqs.join(',')}.`,
+        `Mesaj icerigi wake bildirimine kopyalanmadi. Kendi runtime'ina ait kayitli ChatV3 kimliginle bu channel/room'u ${Math.max(0, first - 1)} cursor'undan sonra oku.`,
+        `Yerel AOPS API: ${config.apiBaseUrl}. Bu bildirim baska bir ajanin --session veya --session-owner degerini bilerek tasimaz.`,
+        'Oda guidance kurallarina uy; dogrudan talimat veya soru varsa kisa ACK ver ve isi ele al.',
+    ].join('\n');
+}
+export function readWakeWatchState(statePath, initialCursor) {
+    try {
+        const value = JSON.parse(readFileSync(statePath, 'utf8'));
+        if (!record(value) || value.version !== 1 || !Number.isSafeInteger(value.cursor) || value.cursor < 0 || !Array.isArray(value.processed) || !value.processed.every((entry) => typeof entry === 'string'))
+            throw new Error('state contract invalid');
+        return { version: 1, cursor: value.cursor, processed: value.processed.slice(-1000), updatedAt: typeof value.updatedAt === 'string' ? value.updatedAt : null };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { version: 1, cursor: initialCursor, processed: [], updatedAt: null };
+        throw new Error(`Cannot read wake-watch state: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function writeWakeWatchState(statePath, state) {
+    mkdirSync(path.dirname(statePath), { recursive: true, mode: 0o700 });
+    const temporary = `${statePath}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify({ ...state, processed: state.processed.slice(-1000), updatedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, statePath);
+}
+export const computeWakeWatchBackoff = (failures, maximum) => Math.min(1000 * 2 ** Math.min(Math.max(failures - 1, 0), 6), maximum);
+const errorText = (error) => error instanceof Error ? error.message : String(error);
+export function wakeWatchMemberAuthReason(error) {
+    if (!record(error) || !record(error.details))
+        return null;
+    const reason = error.details.memberAuthReason;
+    return typeof reason === 'string' && MEMBER_AUTH_REASONS.has(reason)
+        ? reason
+        : null;
+}
+export function isWakeWatchMemberCredentialError(error) {
+    const reason = wakeWatchMemberAuthReason(error);
+    return reason !== null && RECOVERABLE_MEMBER_AUTH_REASONS.has(reason);
+}
+export function isWakeWatchFatalIdentityError(error) {
+    const memberAuthReason = wakeWatchMemberAuthReason(error);
+    if (memberAuthReason)
+        return !RECOVERABLE_MEMBER_AUTH_REASONS.has(memberAuthReason);
+    const message = errorText(error);
+    return /(?:unknown|missing|invalid|not found|not active|removed|ended).{0,40}(?:chatv3 )?session|(?:chatv3 )?session.{0,40}(?:unknown|missing|invalid|not found)|channel.{0,40}(?:mismatch|not found)|room.{0,40}not found|member(?:ship)?.{0,40}(?:not found|not active|removed|ended)/i.test(message);
+}
+function classifiedMemberAuthError(message, reason) {
+    const error = new Error(message);
+    if (reason)
+        error.details = { memberAuthReason: reason };
+    return error;
+}
+function acquireLock(statePath) {
+    const lock = `${statePath}.lock`;
+    mkdirSync(path.dirname(lock), { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+            writeFileSync(path.join(lock, 'pid'), `${process.pid}\n`, { mode: 0o600 });
+            return () => rmSync(lock, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const pid = Number(readFileSync(path.join(lock, 'pid'), 'utf8').trim());
+            try {
+                process.kill(pid, 0);
+                throw new Error(`wake-watch already runs as PID ${pid}.`);
+            }
+            catch (probe) {
+                if (probe.code !== 'ESRCH')
+                    throw probe;
+                rmSync(lock, { recursive: true, force: true });
+            }
+        }
+    }
+    throw new Error('Could not acquire wake-watch lock.');
+}
+export function parseWakeWatchNestedCliError(exitCode, stderr) {
+    const rendered = stderr.toString('utf8').trim();
+    try {
+        const payload = JSON.parse(rendered);
+        const structured = record(payload) && record(payload.error) ? payload.error : null;
+        if (structured && typeof structured.message === 'string') {
+            const error = new Error(structured.message);
+            if (typeof structured.errorCode === 'string')
+                error.errorCode = structured.errorCode;
+            if (record(structured.details))
+                error.details = structured.details;
+            return error;
+        }
+    }
+    catch {
+    }
+    return new Error(`nested ChatV3 exit ${exitCode}: ${rendered.split('\n').at(-1) ?? ''}`);
+}
+async function selfCli(args, accepted, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [process.argv[1], ...args], { stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+        let stdout = Buffer.alloc(0);
+        let stderr = Buffer.alloc(0);
+        let settled = false;
+        const finish = (error, value) => { if (settled)
+            return; settled = true; clearTimeout(timer); error ? reject(error) : resolve(value); };
+        const append = (current, chunk) => { const next = Buffer.concat([current, chunk]); if (next.length > MAX_CAPTURE) {
+            child.kill('SIGTERM');
+            finish(new Error('nested command output limit exceeded'));
+        } ; return next; };
+        child.stdout.on('data', (chunk) => { stdout = append(stdout, chunk); });
+        child.stderr.on('data', (chunk) => { stderr = append(stderr, chunk); });
+        child.once('error', (error) => finish(error));
+        child.once('close', (code) => {
+            if (!accepted.includes(code ?? -1))
+                return finish(parseWakeWatchNestedCliError(code, stderr));
+            try {
+                finish(undefined, { exitCode: code ?? 0, payload: JSON.parse(stdout.toString('utf8')) });
+            }
+            catch {
+                finish(new Error('nested ChatV3 returned invalid JSON'));
+            }
+        });
+        const timer = setTimeout(() => { child.kill('SIGTERM'); finish(new Error('nested ChatV3 timed out')); }, timeoutMs);
+    });
+}
+function common(config) { return [...(config.storePath ? ['--store-path', config.storePath] : []), '--session-owner', config.sessionOwner, '--api-base-url', config.apiBaseUrl, '--yes', '--json']; }
+const log = (event, fields = {}) => process.stdout.write(`${JSON.stringify({ at: new Date().toISOString(), event, ...fields })}\n`);
+const defaults = {
+    wake: wakeAgentSession,
+    listen: (config, cursor) => selfCli(['chat', 'listen', '--session', config.chatSession, '--room', config.room, '--after-seq', String(cursor), '--limit', '100', '--timeout-sec', String(config.listenTimeoutSec), '--interval-sec', String(config.intervalSec), ...common(config)], [0, 22], (config.listenTimeoutSec + 15) * 1000),
+    markRead: async (config, cursor, limit) => { await selfCli(['chat', 'read', '--session', config.chatSession, '--room', config.room, '--after-seq', String(cursor), '--limit', String(limit), '--mark-delivered', '--mark-read', ...common(config)], [0], 30_000); },
+    sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+};
+export async function runWakeWatch(config, dependencies = defaults) {
+    const probe = await dependencies.wake({ runtime: 'codex', transport: 'desktop-ipc', sessionId: config.targetSessionId, prompt: 'AOPS wake-watch startup dry-run probe.', dryRun: true });
+    if (!probe.envelope.ok)
+        throw new Error(`startup dry-run probe failed: ${probe.envelope.code}`);
+    const release = acquireLock(config.statePath);
+    let stopping = false;
+    let failures = 0;
+    let credentialRetryPending = false;
+    const stop = () => { stopping = true; };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    try {
+        let state = readWakeWatchState(config.statePath, config.initialCursor);
+        log('wake_watch_started', { cursor: state.cursor, room: config.room, targetSessionHash: config.targetSessionHash, mode: config.once ? 'once' : 'watch' });
+        while (!stopping) {
+            try {
+                const previousCursor = state.cursor;
+                const listened = await dependencies.listen(config, state.cursor);
+                const messages = normalizeWakeWatchMessages(listened.payload, state.cursor);
+                if (listened.exitCode === 22 || messages.length === 0) {
+                    failures = 0;
+                    credentialRetryPending = false;
+                    if (config.once)
+                        break;
+                    continue;
+                }
+                const artifacts = record(listened.payload) && record(listened.payload.artifacts) ? listened.payload.artifacts : {};
+                const channelId = typeof artifacts.channelId === 'string' ? artifacts.channelId : '';
+                const roomId = typeof artifacts.roomId === 'string' ? artifacts.roomId : '';
+                if (!channelId || !roomId)
+                    throw new Error('chat listen artifacts missing channelId/roomId');
+                if (config.verifiedChannelId && channelId !== config.verifiedChannelId) {
+                    throw new Error('fatal ChatV3 identity error: listen channel does not match the owner-isolated watcher session');
+                }
+                const selected = selectWakeWatchBatch(messages, config, state, channelId, roomId);
+                if (selected.triggers.length) {
+                    const wake = await dependencies.wake({ runtime: 'codex', transport: 'desktop-ipc', sessionId: config.targetSessionId, prompt: buildWakeWatchPrompt(config, channelId, roomId, selected.triggers) });
+                    if (!wake.envelope.ok)
+                        throw new Error(`wake failed: ${wake.envelope.code}`);
+                    const keys = selected.triggers.map((message) => wakeWatchIdempotencyKey(channelId, roomId, message.seq, config.targetSessionHash));
+                    state = { ...state, cursor: selected.nextCursor, processed: [...state.processed, ...keys].slice(-1000) };
+                    log('wake_sent', { seq: selected.triggers.map((message) => message.seq) });
+                }
+                else {
+                    state = { ...state, cursor: selected.nextCursor };
+                    log('ignored_batch', { seq: messages.map((message) => message.seq) });
+                }
+                writeWakeWatchState(config.statePath, state);
+                try {
+                    await dependencies.markRead(config, previousCursor, messages.length);
+                }
+                catch (error) {
+                    log('receipt_warning', { error: error instanceof Error ? error.message : String(error) });
+                }
+                failures = 0;
+                credentialRetryPending = false;
+                if (config.once)
+                    break;
+            }
+            catch (error) {
+                const message = errorText(error);
+                const memberAuthReason = wakeWatchMemberAuthReason(error);
+                if (isWakeWatchFatalIdentityError(error)) {
+                    throw classifiedMemberAuthError(`fatal ChatV3 identity error: ${message}`, memberAuthReason);
+                }
+                if (isWakeWatchMemberCredentialError(error)) {
+                    if (credentialRetryPending) {
+                        throw classifiedMemberAuthError(`member credential remained invalid after one automatic recovery attempt: ${message}`, memberAuthReason);
+                    }
+                    credentialRetryPending = true;
+                    log('wake_watch_credential_recovery', {
+                        action: 'reload_saved_session_and_retry_once',
+                        memberAuthReason,
+                    });
+                    continue;
+                }
+                if (config.once)
+                    throw error;
+                failures += 1;
+                if (failures >= config.maxConsecutiveFailures) {
+                    throw new Error(`maximum consecutive failures reached (${config.maxConsecutiveFailures}): ${message}`);
+                }
+                const backoffMs = computeWakeWatchBackoff(failures, config.maxBackoffMs);
+                log('wake_watch_error', { error: message, backoffMs });
+                await (dependencies.sleep ?? defaults.sleep)(backoffMs);
+            }
+        }
+    }
+    finally {
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+        release();
+        log('wake_watch_stopped');
+    }
+}
+export function makeChatWakeWatchCommand() {
+    return new Command('wake-watch').description('EXPERIMENTAL foreground ChatV3-to-local-Codex wake watcher')
+        .requiredOption('--session <id>', 'Watcher-owned local ChatV3 session').option('--room <slugOrId>', 'Room slug or id', 'general')
+        .requiredOption('--target-session-id <uuid>', 'Exact local Codex task UUID').requiredOption('--watcher-member-id <uuid>', 'Watcher ChatV3 member id')
+        .requiredOption('--target-member-id <uuid>', 'Target agent ChatV3 member id').option('--ignore-member <uuid>', 'Repeatable explicit ignore-set member id', (value, previous) => [...previous, value], [])
+        .requiredOption('--wake-approved', 'Confirm operator approval for local session wake').option('--once', 'Run one bounded listen cycle').option('--after-seq <seq>', 'Initial processing cursor', '0')
+        .option('--state-path <path>', 'Processing-state override').option('--store-path <path>', 'ChatV3 session store override').option('--session-owner <id>', 'Watcher session owner')
+        .option('--api-base-url <url>', 'AOPS API base URL').option('--listen-timeout-sec <n>', 'Listen timeout', '30').option('--interval-sec <n>', 'Poll interval', '2').option('--max-backoff-ms <n>', 'Maximum retry backoff', '30000').option('--max-consecutive-failures <n>', 'Stop after this many transient failures', '10')
+        .option('--yes', 'Non-interactive').option('--json', 'JSON-lines status').action(async (options) => { try {
+        const config = await preflightWakeWatchSession(resolveWakeWatchConfig(options));
+        await runWakeWatch(config);
+    }
+    catch (error) {
+        log('wake_watch_fatal', { error: error instanceof Error ? error.message : String(error), memberAuthReason: wakeWatchMemberAuthReason(error) });
+        process.exitCode = 1;
+    } })
+        .addHelpText('after', '\nEXPERIMENTAL / UNSUPPORTED\n  Chat-triggered wake requires this watcher\'s owner-isolated active channel member token; the token and member id must match before IPC probing or listen begins.\n  Uses version-sensitive Codex Desktop IPC. Startup fails closed unless the ignore-set is complete and dry-run owner probing succeeds.\n  Message text, the target Codex session id, and another agent\'s ChatV3 session/owner identity are never copied into ChatV3 coordination.\n  This is a normal-flow identity boundary, not isolation from another local process running as the same OS user.\n');
+}

package/dist/commands/chatv3.js

@@ -6,7 +6,26 @@ import { resolveCliApiBaseUrl } from '../utils/api.js';
 import { planChatv3SendCursorAdvance } from '../utils/chatv3-cursor.js';
 import { applyCommonOptions, compactPayload, normalizeNonEmpty } from '../utils/command.js';
 import { buildOperatorCookbook } from '../utils/hosted-sugar.js';
+import { makeChatWakeWatchCommand } from './chat-wake-watch.js';
 import { deleteChatv3Session, getChatv3SessionRecord, listChatv3SessionRecords, loadChatv3Session, resolveChatv3SessionStorePath, resolveChatv3SessionOwner, saveChatv3Session, summarizeChatv3Session, } from '../utils/chatv3-session-store.js';
+const CHATV3_MEMBER_TOKEN_ID = /^cv3m_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})_/i;
+export function memberIdFromChatv3Token(memberToken) {
+    return CHATV3_MEMBER_TOKEN_ID.exec(memberToken)?.[1] ?? null;
+}
+export function isChatv3MemberCredentialError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /(member token (?:mismatch|required|unknown|not found)|unknown member token|invalid member token(?: format)?|membership is not active)/i.test(message);
+}
+export class Chatv3IdentityRecoveryError extends Error {
+    code = 'chatv3_identity_recovery_failed';
+    constructor(sessionId, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`Automatic exact-member token recovery failed for ChatV3 session "${sessionId}": ${detail}`, {
+            cause: cause instanceof Error ? cause : undefined,
+        });
+        this.name = 'Chatv3IdentityRecoveryError';
+    }
+}
 const AGENT_BOOTSTRAP_STEPS = [
     'Read channel and active-room rules before acting.',
     'Use chat for coordination and wake; use PM for task/review truth.',
@@ -26,6 +45,7 @@ const CHATV3_COMMAND_TREE = {
     send: null,
     read: null,
     listen: null,
+    'wake-watch': null,
     leave: null,
     binding: new Set(['add', 'list', 'remove']),
     member: new Set(['list', 'remove', 'restore']),
@@ -510,7 +530,7 @@ async function persistRuntimeSnapshot(runtime, activeRoomId) {
         owner: runtime.sessionOwner,
     });
 }
-async function loadRuntime(options, sessionId) {
+async function loadRuntimeAttempt(options, sessionId) {
     const storePath = resolveChatv3SessionStorePath(options.storePath, options.sessionOwner);
     const loaded = await loadChatv3Session(sessionId, {
         storePath: options.storePath,
@@ -566,6 +586,58 @@ async function loadRuntime(options, sessionId) {
     await persistRuntimeSnapshot(runtime);
     return runtime;
 }
+function plainSessionInput(loaded) {
+    return {
+        id: loaded.record.id,
+        serverBaseUrl: loaded.record.serverBaseUrl,
+        handle: loaded.record.handle,
+        channel: loaded.record.channel,
+        keyId: loaded.record.keyId,
+        activeRoomId: loaded.record.activeRoomId,
+        rooms: loaded.record.rooms,
+        createdAt: loaded.record.createdAt,
+    };
+}
+async function recoverStoredMemberToken(options, sessionId) {
+    const loaded = await loadChatv3Session(sessionId, {
+        storePath: options.storePath,
+        owner: options.sessionOwner,
+    });
+    if (loaded.record.channel.encryptionMode !== 'server-encrypted') {
+        throw new Error('exact-member token recovery is available only for server-encrypted channels');
+    }
+    const memberId = memberIdFromChatv3Token(loaded.secrets.memberToken);
+    if (!memberId)
+        throw new Error('stored member token does not contain a recoverable member identity');
+    const serverBaseUrl = normalizeNonEmpty(options.apiBaseUrl) ?? loaded.record.serverBaseUrl;
+    const client = new Chatv3Client({ serverBaseUrl });
+    const recovered = await client.http.post(`/channels/${loaded.record.channel.id}/members/${memberId}/token`, {
+        tenantId: loaded.record.channel.tenantId,
+        channelId: loaded.record.channel.id,
+        memberId,
+    });
+    if (recovered.member.id !== memberId || memberIdFromChatv3Token(recovered.memberToken) !== memberId) {
+        throw new Error('server returned a token for a different member identity');
+    }
+    await saveChatv3Session(plainSessionInput(loaded), { ...loaded.secrets, memberToken: recovered.memberToken }, { storePath: options.storePath, owner: options.sessionOwner });
+    process.stderr.write(`[chatv3] Recovered the exact member credential for session "${sessionId}".\n`);
+}
+async function loadRuntime(options, sessionId) {
+    try {
+        return await loadRuntimeAttempt(options, sessionId);
+    }
+    catch (error) {
+        if (!isChatv3MemberCredentialError(error))
+            throw error;
+        try {
+            await recoverStoredMemberToken(options, sessionId);
+            return await loadRuntimeAttempt(options, sessionId);
+        }
+        catch (recoveryError) {
+            throw new Chatv3IdentityRecoveryError(sessionId, recoveryError);
+        }
+    }
+}
 function channelMatchesSelector(channel, selector) {
     return channel.id === selector || channel.slug === selector || (selector.length >= 8 && channel.id.startsWith(selector));
 }
@@ -1837,6 +1909,7 @@ export function makeChatv3Command(commandName = 'chat') {
         .option('--mark-read', 'Advance read cursor to the highest returned seq')).action(async (options) => {
         await runChatv3Listen(options);
     });
+    cmd.addCommand(makeChatWakeWatchCommand());
     const binding = cmd.command('binding').description('ChatV3 loose channel/room reference bindings');
     applyChatv3Options(binding.command('add')
         .description('Attach a loose external reference to the active room or channel')

package/dist/commands/codex.js

@@ -0,0 +1,161 @@
+import { AGENT_RUNTIME_WAKE_MAX_PROMPT_BYTES, listAgentWakeTargets, registerAgentWakeTarget, resolveAgentWakeRegistryPath, unregisterAgentWakeTarget, wakeAgentSession, } from '@aopslabs/aops-agent-runtime';
+import { Command } from 'commander';
+async function readBoundedStdin() {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8');
+        bytes += buffer.length;
+        if (bytes > AGENT_RUNTIME_WAKE_MAX_PROMPT_BYTES) {
+            throw new Error(`Prompt exceeds ${AGENT_RUNTIME_WAKE_MAX_PROMPT_BYTES} UTF-8 bytes.`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function failureEnvelope(options, code, message) {
+    return {
+        ok: false,
+        code,
+        transport: options.transport ?? 'desktop-ipc',
+        runtime: 'codex',
+        sessionId: options.sessionId ?? '',
+        ownerClientId: null,
+        turnId: null,
+        protocolVersion: null,
+        protocolVersionVerified: false,
+        runtimeVersion: null,
+        runtimeVersionSupported: false,
+        stage: 'validation',
+        message,
+        retryable: false,
+    };
+}
+async function runCodexWake(options) {
+    let prompt = options.prompt ?? '';
+    try {
+        if (prompt === '-')
+            prompt = await readBoundedStdin();
+    }
+    catch (error) {
+        process.stdout.write(`${JSON.stringify(failureEnvelope(options, 'prompt_read_failed', error instanceof Error ? error.message : String(error)))}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    const result = await wakeAgentSession({
+        runtime: 'codex',
+        sessionId: options.sessionId ?? '',
+        prompt,
+        transport: options.transport ?? 'desktop-ipc',
+        dryRun: options.dryRun === true,
+    });
+    process.stdout.write(`${JSON.stringify(result.envelope)}\n`);
+    if (result.exitCode !== 0)
+        process.exitCode = result.exitCode;
+}
+function writeRegistryResult(payload, exitCode = 0) {
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+    if (exitCode !== 0)
+        process.exitCode = exitCode;
+}
+async function runCodexRegister(options) {
+    const sessionId = options.sessionId ?? '';
+    const probe = await wakeAgentSession({ runtime: 'codex', transport: 'desktop-ipc', sessionId, prompt: '', dryRun: true });
+    if (!probe.envelope.ok) {
+        writeRegistryResult(probe.envelope, probe.exitCode);
+        return;
+    }
+    try {
+        const entry = registerAgentWakeTarget({
+            channelId: options.channelId ?? '',
+            memberId: options.memberId ?? '',
+            handle: options.handle,
+            targetSessionId: sessionId,
+            registryPath: options.registryPath,
+        });
+        writeRegistryResult({
+            ok: true,
+            code: 'agent_wake_target_registered',
+            runtime: entry.runtime,
+            channelId: entry.channelId,
+            memberId: entry.memberId,
+            handle: entry.handle,
+            targetSessionIdHash: entry.targetSessionIdHash,
+            hostMatched: true,
+            lastVerifiedAt: entry.lastVerifiedAt,
+        });
+    }
+    catch (error) {
+        writeRegistryResult({ ok: false, code: 'agent_wake_registry_write_failed', message: error instanceof Error ? error.message : String(error) }, 1);
+    }
+}
+function runCodexRegistrations(options) {
+    try {
+        const entries = listAgentWakeTargets(options.registryPath).map((entry) => ({
+            runtime: entry.runtime,
+            channelId: entry.channelId,
+            memberId: entry.memberId,
+            handle: entry.handle,
+            targetSessionIdHash: entry.targetSessionIdHash,
+            lastVerifiedAt: entry.lastVerifiedAt,
+        }));
+        writeRegistryResult({ ok: true, code: 'agent_wake_registrations', registryPath: resolveAgentWakeRegistryPath(options.registryPath), entries });
+    }
+    catch (error) {
+        writeRegistryResult({ ok: false, code: 'agent_wake_registry_read_failed', message: error instanceof Error ? error.message : String(error) }, 1);
+    }
+}
+function runCodexUnregister(options) {
+    try {
+        const removed = unregisterAgentWakeTarget(options.channelId ?? '', options.memberId ?? '', options.registryPath);
+        writeRegistryResult({ ok: true, code: removed ? 'agent_wake_target_unregistered' : 'agent_wake_target_not_found', channelId: options.channelId, memberId: options.memberId });
+    }
+    catch (error) {
+        writeRegistryResult({ ok: false, code: 'agent_wake_registry_write_failed', message: error instanceof Error ? error.message : String(error) }, 1);
+    }
+}
+export function makeCodexCommand() {
+    const command = new Command('codex')
+        .description('Experimental local agent-runtime integrations for Codex Desktop');
+    command
+        .command('wake')
+        .alias('wakeup')
+        .description('Wake the exact local Codex Desktop session through internal IPC')
+        .option('--session-id <uuid>', 'Exact Codex Desktop task/session UUID')
+        .option('--prompt <text-or-dash>', 'Bounded prompt text, or - to read it from stdin')
+        .option('--transport <transport>', 'Transport (only desktop-ipc is supported)', 'desktop-ipc')
+        .option('--dry-run', 'Probe the exact local owner without sending a turn')
+        .action(runCodexWake)
+        .addHelpText('after', `
+EXPERIMENTAL / UNSUPPORTED
+  desktop-ipc is an internal, version-sensitive Codex Desktop protocol.
+  This command fails closed and never falls back to the public SDK or app-server.
+  A successful non-dry-run injects the bounded prompt into the selected local task.
+  This low-level local IPC primitive is not a ChatV3 authorization surface.
+  Chat-triggered wake must first prove the caller's owner-isolated active channel member token in the watcher or Cockpit flow.
+  These checks prevent normal-flow member substitution; they do not isolate another process running as the same OS user.
+`);
+    command
+        .command('register')
+        .description('Register a verified local Codex task for one ChatV3 agent member')
+        .requiredOption('--channel-id <uuid>', 'Exact ChatV3 channel UUID')
+        .requiredOption('--member-id <uuid>', 'Exact ChatV3 agent member UUID')
+        .option('--handle <handle>', 'Expected ChatV3 handle for identity binding')
+        .requiredOption('--session-id <uuid>', 'Exact local Codex task/session UUID')
+        .option('--registry-path <path>', 'Local registry override for named-instance testing')
+        .action(runCodexRegister)
+        .addHelpText('after', '\nEXPERIMENTAL / UNSUPPORTED\n  Registration writes only after a live fail-closed Desktop owner dry-run succeeds.\n  The registry is local, atomic, owner-only (0600 on POSIX), and host-bound.\n');
+    command
+        .command('registrations')
+        .description('List local ChatV3-to-Codex registrations with session ids redacted')
+        .option('--registry-path <path>', 'Local registry override')
+        .action(runCodexRegistrations);
+    command
+        .command('unregister')
+        .description('Remove one local ChatV3 member wake registration')
+        .requiredOption('--channel-id <uuid>', 'Exact ChatV3 channel UUID')
+        .requiredOption('--member-id <uuid>', 'Exact ChatV3 agent member UUID')
+        .option('--registry-path <path>', 'Local registry override')
+        .action(runCodexUnregister);
+    return command;
+}