pendingyou 0.9.0 → 0.11.0

package/dist/apps/codex-wake.js

@@ -0,0 +1,386 @@
+// Codex hearing answers (0.11.0): what its hooks remember about the cards a thread posted, and the listener that wakes
+// the thread when one is answered.
+//
+// - `pendingyou posted --app codex` is Codex's PostToolUse hook for Pending You's card tools (post_request,
+//   update_request, reply_in_thread, cancel_request; Codex runs it only for a call that didn't fail). It records that
+//   the turn put something in front of the person (with the card's words, for the Stop check: stopcheck.ts), and which
+//   thread is waiting on which card (`session_id` is the thread's id), then makes sure that thread has a listener.
+// - `pendingyou listen --app codex --thread <id>` is that listener: one per thread (a lease file), detached, holding no
+//   hook's output (Codex would wait for it otherwise). It long-polls Pending You with Codex's own connection, as `watch`
+//   does, and when one of the thread's cards is the agent's move (an answer, a message, a fallback that ran) it runs
+//   `codex queue --thread <id> --message "Pending You: your person answered …"`, in the words the Claude Code wake mod
+//   uses. Never the answer itself: a program's arguments are there for any other program on the computer to read, so
+//   the agent reads the answer with get_request, as the message says. Codex starts a turn at once when the thread is
+//   loaded and idle, after the current one when it's working, or when it's next resumed. It stops when the thread has no card left waiting, or after 8
+//   hours; the next session start or message starts it again while one is (pickup.ts).
+//
+// Ids, names and titles only, in ~/.config/pendingyou/codex-threads.json: never an answer.
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getJson, SignInNeeded, Unavailable } from "../api.js";
+import { DEFAULT_ORIGIN } from "../args.js";
+import { readCredential } from "../credentials.js";
+import { configDir, readJson, withLock, writeWhole } from "../files.js";
+import { clip, isClosed } from "../format.js";
+import { markHanded, momentOf, wasHanded } from "../state.js";
+/** How long a turn's record, and a thread untouched, are kept. */
+const KEEP_TURN_MS = 24 * 60 * 60_000;
+const KEEP_THREAD_MS = 7 * 24 * 60 * 60_000;
+/** The most of one card's words a turn keeps, to match an ask against (stopcheck.ts). */
+const CARD_WORDS = 20_000;
+/** How long a listener waits on one thread, at most, and how often it renews its lease. */
+export const LISTEN_MS = 8 * 60 * 60_000;
+const LONG_POLL_SECONDS = 25;
+/** A lease untouched for this long belongs to a listener that died. */
+const LEASE_STALE_MS = 90_000;
+const PATIENT_AFTER_MS = 30 * 60_000;
+const PATIENT_PAUSE_MS = 30_000;
+const BACKOFF_MS = [2000, 5000, 10_000, 20_000, 30_000, 60_000];
+const REQUEST_ID = /^req_[A-Za-z0-9-]{1,40}$/;
+/** Codex's tools for the card calls the hook reads, on a Pending You server (`mcp__pendingyou__post_request`). */
+const CARD_TOOL = /^mcp__([A-Za-z0-9_]*pendingyou[A-Za-z0-9_]*)__(post_request|update_request|reply_in_thread|cancel_request)$/i;
+const statePath = (io) => join(configDir(io), 'codex-threads.json');
+const leasePath = (io, thread) => join(configDir(io), 'codex-listen', `${thread}.lease`);
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+async function load(io) {
+    const file = await readJson(statePath(io)).catch(() => null);
+    return {
+        version: 1,
+        threads: isObject(file?.threads) ? file.threads : {},
+        turns: isObject(file?.turns) ? file.turns : {},
+    };
+}
+/** Changes the state under its lock, dropping what's old. */
+async function change(io, edit) {
+    const path = statePath(io);
+    return withLock(path, io, async () => {
+        const state = await load(io);
+        edit(state);
+        const now = io.now();
+        for (const [id, turn] of Object.entries(state.turns))
+            if (!(now - turn.at < KEEP_TURN_MS))
+                delete state.turns[id];
+        for (const [id, thread] of Object.entries(state.threads))
+            if (!(now - thread.at < KEEP_THREAD_MS) || Object.keys(thread.cards).length === 0)
+                delete state.threads[id];
+        await writeWhole(path, `${JSON.stringify(state, null, 2)}\n`, { secret: true });
+        return state;
+    });
+}
+/** A tool's answer as Codex hands it to PostToolUse (a CallToolResult): its JSON object, or null. */
+export function resultOf(response) {
+    if (!isObject(response) || response.isError === true)
+        return null;
+    if (isObject(response.structuredContent))
+        return response.structuredContent;
+    const blocks = Array.isArray(response.content) ? response.content : [];
+    for (const block of blocks) {
+        if (!isObject(block) || typeof block.text !== 'string')
+            continue;
+        try {
+            const parsed = JSON.parse(block.text);
+            if (isObject(parsed))
+                return parsed;
+        }
+        catch { }
+    }
+    return null;
+}
+/** Every string a call carried (a card's title, summary, steps…), up to `max` characters: what a card says. */
+export function wordsIn(value, max = CARD_WORDS) {
+    const found = [];
+    let left = max;
+    const walk = (item, depth) => {
+        if (left <= 0 || depth > 8)
+            return;
+        if (typeof item === 'string') {
+            found.push(item.slice(0, left));
+            left -= item.length;
+        }
+        else if (Array.isArray(item))
+            for (const each of item)
+                walk(each, depth + 1);
+        else if (isObject(item))
+            for (const each of Object.values(item))
+                walk(each, depth + 1);
+    };
+    walk(value, 0);
+    return found.join('\n');
+}
+const text = (value, max) => typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : undefined;
+/** The agent's name on a call: `name`, or post_request's `session.label`. */
+function nameOf(input) {
+    const session = isObject(input.session) ? input.session : null;
+    return text(input.name, 120) ?? text(session?.label, 120);
+}
+/**
+ * `pendingyou posted --app codex`: Codex's PostToolUse hook. Remembers what the turn put in front of the person and
+ * which cards the thread waits on, then makes sure the thread has a listener. Prints nothing (Codex ignores it anyway);
+ * never fails.
+ */
+export async function posted(io, options) {
+    try {
+        const input = JSON.parse(await io.readStdin(1000));
+        if (!isObject(input))
+            return 0;
+        const tool = typeof input.tool_name === 'string' ? CARD_TOOL.exec(input.tool_name) : null;
+        const thread = typeof input.session_id === 'string' ? input.session_id : null;
+        const turn = typeof input.turn_id === 'string' ? input.turn_id : null;
+        if (!tool || !thread)
+            return 0;
+        const call = tool[2];
+        const args = isObject(input.tool_input) ? input.tool_input : {};
+        const output = resultOf(input.tool_response);
+        const requestId = [output?.requestId, args.requestId].find((id) => typeof id === 'string' && REQUEST_ID.test(id));
+        const now = io.now();
+        const state = await change(io, (state) => {
+            if (turn && call !== 'cancel_request') {
+                const record = state.turns[turn] ?? { at: now, cards: [] };
+                record.cards = [...record.cards, wordsIn(args)].slice(-10);
+                record.at = now;
+                state.turns[turn] = record;
+            }
+            if (!requestId)
+                return;
+            const waiting = state.threads[thread] ?? { origin: options.origin, cards: {}, at: now };
+            const reopen = isObject(args.reopen) ? args.reopen : null;
+            if (call === 'cancel_request')
+                delete waiting.cards[requestId];
+            // A reply that leaves it the agent's turn (an answer to their message) isn't waiting on them.
+            else if (call !== 'reply_in_thread' || reopen || output?.turn === 'you') {
+                const before = waiting.cards[requestId];
+                const name = nameOf(args) ?? before?.name;
+                const title = text(args.title, 400) ?? text(reopen?.title, 400) ?? before?.title;
+                waiting.cards[requestId] = {
+                    ...(name ? { name } : {}),
+                    ...(title ? { title } : {}),
+                    at: now,
+                };
+            }
+            waiting.origin = options.origin;
+            waiting.at = now;
+            state.threads[thread] = waiting;
+        });
+        if (Object.keys(state.threads[thread]?.cards ?? {}).length > 0)
+            await keepListening(io, options.origin, thread);
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Whether this turn put something in front of the person, the words of each card, and whether it was nudged. */
+export async function turnRecord(io, turn) {
+    const record = (await load(io)).turns[turn];
+    return record ? { cards: record.cards, nudged: record.nudged === true } : null;
+}
+/** Remembers that the Stop check asked this turn to go on: at most once a turn. */
+export async function markNudged(io, turn) {
+    const now = io.now();
+    await change(io, (state) => {
+        state.turns[turn] = { ...(state.turns[turn] ?? { cards: [] }), at: now, nudged: true };
+    });
+}
+/** Whether a listener holds this thread now: its lease, touched within LEASE_STALE_MS. */
+async function listening(io, thread) {
+    return stat(leasePath(io, thread)).then((info) => Date.now() - info.mtimeMs < LEASE_STALE_MS, () => false);
+}
+/**
+ * Makes sure a thread with cards waiting on the person has a listener: starts one, detached, unless one is there or
+ * Codex isn't signed in. Quick (three small reads) and never throws: the session-start and next-message hooks call it too.
+ */
+export async function keepListening(io, origin, thread) {
+    try {
+        if (!/^[A-Za-z0-9][A-Za-z0-9-]{0,99}$/.test(thread))
+            return;
+        const cards = (await load(io)).threads[thread]?.cards ?? {};
+        if (Object.keys(cards).length === 0 || (await listening(io, thread)))
+            return;
+        if (!(await readCredential(io, origin, 'codex')))
+            return;
+        io.background([
+            'listen',
+            '--app',
+            'codex',
+            '--thread',
+            thread,
+            ...(origin === DEFAULT_ORIGIN ? [] : ['--origin', origin]),
+        ]);
+    }
+    catch { }
+}
+/** What happened to a card and what to do, in the words the Claude Code wake mod uses (wake.ts's line). */
+function line(heard, card) {
+    const titled = `“${clip(card.title ?? heard.title, 80)
+        .text.replaceAll('“', '‘')
+        .replaceAll('”', '’')}” (${heard.requestId})`;
+    const named = card.name ?? heard.sessionLabel;
+    const get = `get_request (requestId ${heard.requestId}, ${named ? `name “${named}”` : 'your name'})`;
+    switch (heard.status) {
+        case 'expired':
+            return [
+                `nobody answered ${titled} in time, so its fallback is due`,
+                'do it now if you haven’t already; there’s nothing to acknowledge',
+            ];
+        case 'cancelled':
+        case 'resolved':
+            return null;
+        case 'answered':
+            return [
+                `your person answered ${titled}`,
+                `call ${get}, act on their words, then ack_answer with its version and a one-line outcome`,
+            ];
+        default:
+            return [
+                `your person wrote to you on ${titled}`,
+                `call ${get} to read it, then answer with reply_in_thread`,
+            ];
+    }
+}
+const capital = (sentence) => sentence.charAt(0).toUpperCase() + sentence.slice(1);
+/** The message that wakes the thread: every card that needs it, and what to do with each; null when none does. */
+export function wakeMessage(ready) {
+    const lines = ready.flatMap(({ heard, card }) => {
+        const said = line(heard, card);
+        return said ? [{ heard, said }] : [];
+    });
+    if (lines.length === 0)
+        return null;
+    const asked = lines.some(({ heard }) => heard.turn === 'agent' && heard.status !== 'expired');
+    const reopen = asked
+        ? ' If they asked you something or you need more from them, reply_in_thread with reopen instead.'
+        : '';
+    if (lines.length === 1) {
+        const [happened, todo] = lines[0].said;
+        return `Pending You: ${happened}. ${capital(todo)}.${reopen}`;
+    }
+    return [
+        `Pending You: ${lines.length} of your cards need you.`,
+        ...lines.map(({ said: [happened, todo] }) => `- ${capital(happened)}: ${todo}.`),
+        ...(reopen ? [reopen.trim()] : []),
+    ].join('\n');
+}
+/**
+ * Takes the thread's lease, a file holding this listener's own id: null when a live listener holds it. Two listeners
+ * starting at once may both write it; the one whose id isn't there at its next renewal stops.
+ */
+async function takeLease(io, thread) {
+    const path = leasePath(io, thread);
+    await mkdir(join(path, '..'), { recursive: true, mode: 0o700 });
+    if (await listening(io, thread))
+        return null;
+    const id = randomBytes(8).toString('hex');
+    await rm(path, { recursive: true, force: true });
+    try {
+        await writeFile(path, id, { flag: 'wx', mode: 0o600 });
+        return id;
+    }
+    catch {
+        return null;
+    }
+}
+/** Renews the lease while it's still this listener's (`id`); false once another listener has taken it. */
+async function renew(io, thread, id) {
+    const path = leasePath(io, thread);
+    if ((await readFile(path, 'utf8').catch(() => null)) !== id)
+        return false;
+    const now = new Date();
+    await utimes(path, now, now).catch(() => { });
+    return true;
+}
+/**
+ * `pendingyou listen --app codex --thread <id>`: waits on Pending You for the thread's cards, and wakes the thread
+ * with `codex queue` when one is the agent's move. Quiet; exits when the thread has none left, Codex can't be reached,
+ * the sign-in ends, or after LISTEN_MS.
+ */
+export async function listen(io, options) {
+    const { origin, thread } = options;
+    const lease = await takeLease(io, thread);
+    if (!lease)
+        return 0;
+    try {
+        const started = io.now();
+        let since;
+        let failures = 0;
+        while (io.now() - started < LISTEN_MS && !io.signal.aborted) {
+            const cards = (await load(io)).threads[thread]?.cards ?? {};
+            if (Object.keys(cards).length === 0)
+                return 0;
+            if (!(await renew(io, thread, lease)))
+                return 0;
+            const query = new URLSearchParams({
+                source: 'codex',
+                limit: '20',
+                wait: String(LONG_POLL_SECONDS),
+            });
+            if (since)
+                query.set('since', since);
+            let requests;
+            try {
+                const { status, body } = await getJson(io, origin, `/mcp/cli/answers?${query}`, (LONG_POLL_SECONDS + 20) * 1000, io.signal, { app: 'codex' });
+                if (status !== 200)
+                    throw new Unavailable(`Pending You answered ${status}.`);
+                requests = Array.isArray(body.requests) ? body.requests : [];
+                failures = 0;
+            }
+            catch (error) {
+                if (error instanceof SignInNeeded || io.signal.aborted)
+                    return 0;
+                // Renewed first: no pause here outlasts the lease.
+                if (!(await renew(io, thread, lease)))
+                    return 0;
+                await io.sleep(BACKOFF_MS[Math.min(failures++, BACKOFF_MS.length - 1)], io.signal);
+                continue;
+            }
+            for (const heard of requests)
+                if (!since || heard.changedAt > since)
+                    since = heard.changedAt;
+            const ready = [];
+            const done = [];
+            for (const heard of requests) {
+                const card = cards[heard.requestId];
+                if (!card || !heard.ready)
+                    continue;
+                // Handed over already (the person wrote in Codex since): nothing to wake it for.
+                if (await wasHanded(io, origin, heard.requestId, momentOf(heard)))
+                    done.push(heard.requestId);
+                else
+                    ready.push({ heard, card });
+            }
+            const message = wakeMessage(ready);
+            if (message) {
+                const queued = await io.run('codex', ['queue', '--thread', thread, '--message', message], 30_000);
+                // Codex doesn't know the thread (archived, gone), or can't be run from here: the hooks hand answers over.
+                if (queued.code !== 0) {
+                    await change(io, (state) => {
+                        delete state.threads[thread];
+                    });
+                    return 0;
+                }
+                await markHanded(io, origin, ready.map(({ heard }) => ({ requestId: heard.requestId, moment: momentOf(heard) })));
+            }
+            for (const { heard } of ready)
+                done.push(heard.requestId);
+            // Closed cards nobody needs telling about go too.
+            for (const heard of requests)
+                if (cards[heard.requestId] && isClosed(heard) && !done.includes(heard.requestId))
+                    done.push(heard.requestId);
+            if (done.length)
+                await change(io, (state) => {
+                    const waiting = state.threads[thread];
+                    if (waiting)
+                        for (const id of done)
+                            delete waiting.cards[id];
+                });
+            if (io.now() - started > PATIENT_AFTER_MS)
+                await io.sleep(PATIENT_PAUSE_MS, io.signal);
+        }
+        return 0;
+    }
+    finally {
+        // Only its own: a listener that took over keeps the thread.
+        if ((await readFile(leasePath(io, thread), 'utf8').catch(() => null)) === lease)
+            await rm(leasePath(io, thread), { force: true }).catch(() => { });
+    }
+}