workoffdesk 0.0.0-stage → 1.0.0

package/dist/server/agents/claude/transcript/turn.js

@@ -0,0 +1,136 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+// What Claude Code's transcript says of the turn it is on, read from its end: whether the turn is over, and
+// what Claude still holds in its own queue. A message typed while it works waits there (enqueue) until it is
+// taken into the turn under way (remove), starts a turn of its own (dequeue) or is pulled back into the
+// prompt to be changed (popAll).
+// The end of the transcript read for it: what was typed long before was taken long ago.
+const TAIL_BYTES = 256 * 1024;
+const INTERRUPTED = '[Request interrupted';
+const COMMAND = /<command-name>/;
+const COMMAND_OUTPUT = /^<local-command-std(out|err)>/;
+// The entries of the lines, but for commands Claude Code ran on its own (/model, /effort): each is written as
+// the command and its output, and is no part of any turn. A command whose prompt goes to Claude (/review)
+// has no output of its own and stays, as the prompt of its turn.
+function entries(lines, wanted) {
+    const out = [];
+    for (const line of lines) {
+        if (!wanted(line))
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (!e || typeof e !== 'object')
+                continue;
+            if (userSays(e, COMMAND_OUTPUT)) {
+                const command = out.findLastIndex((x) => userSays(x, COMMAND));
+                if (command >= 0)
+                    out.splice(command, 1);
+                continue;
+            }
+            out.push(e);
+        }
+        catch {
+            // a line cut off by the end of what was read, or one being written
+        }
+    }
+    return out;
+}
+const texts = (content) => typeof content === 'string'
+    ? [content]
+    : Array.isArray(content)
+        ? content.flatMap((b) => (b?.type === 'text' && typeof b.text === 'string' ? [b.text] : []))
+        : [];
+const userSays = (e, text) => e.type === 'user' && texts(e.message?.content).some((t) => text.test(t));
+// The messages Claude still holds, oldest first, by the queue operations since the last turn began: what
+// was held before then was taken by then.
+export function heldByClaude(lines) {
+    const held = [];
+    for (const e of entries(lines, (l) => l.includes('"queue-operation"') || l.includes('"user"'))) {
+        if (startsTurn(e))
+            held.length = 0;
+        if (e.type !== 'queue-operation')
+            continue;
+        if (e.operation === 'enqueue')
+            held.push(typeof e.content === 'string' ? e.content : '');
+        else if (e.operation === 'dequeue')
+            held.shift();
+        else if (e.operation === 'popAll')
+            held.length = 0;
+        else if (e.operation === 'remove') {
+            const i = held.indexOf(e.content);
+            held.splice(i < 0 ? 0 : i, 1);
+        }
+    }
+    return held;
+}
+// A prompt: what a turn begins with, as against the answer to a call, a note or Esc.
+function startsTurn(e) {
+    if (e.type !== 'user' || e.isMeta === true)
+        return false;
+    const c = e.message?.content;
+    if (Array.isArray(c) && c.every((b) => b?.type === 'tool_result'))
+        return false;
+    return !texts(c).some((t) => t.startsWith(INTERRUPTED));
+}
+// What an entry says of the turn: that it ended there, that the turn goes on, or nothing.
+function said(e) {
+    if (e.type === 'system')
+        return e.subtype === 'stop_hook_summary' ? 'over' : null;
+    if (e.type === 'queue-operation')
+        return e.operation === 'dequeue' ? 'going' : null;
+    if (e.type === 'assistant')
+        return e.isApiErrorMessage === true ? 'over' : 'going';
+    if (e.type === 'user') {
+        if (e.isMeta === true)
+            return null;
+        return texts(e.message?.content).some((t) => t.startsWith(INTERRUPTED)) ? 'over' : 'going';
+    }
+    return null;
+}
+// Whether the turn the lines end in is over, and when it ended; null when they hold no turn.
+export function lastTurn(lines) {
+    const all = entries(lines, () => true);
+    for (let i = all.length - 1; i >= 0; i--) {
+        const s = said(all[i]);
+        if (s === 'going')
+            return { over: false };
+        if (s === 'over') {
+            const at = typeof all[i].timestamp === 'string' ? Date.parse(all[i].timestamp) : NaN;
+            return { over: true, at: Number.isFinite(at) ? at : 0 };
+        }
+    }
+    return null;
+}
+// The end of a transcript on disk, as lines; null when it cannot be read.
+export function transcriptTail(path) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        const size = fstatSync(fd).size;
+        const from = Math.max(0, size - TAIL_BYTES);
+        const buf = Buffer.alloc(size - from);
+        readSync(fd, buf, 0, buf.length, from);
+        const lines = buf.toString('utf8').split('\n');
+        return from > 0 ? lines.slice(1) : lines;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+// heldByClaude for a transcript on disk; none when it cannot be read.
+export function heldInTranscript(path) {
+    const lines = transcriptTail(path);
+    return lines ? heldByClaude(lines) : [];
+}
+// lastTurn for a transcript on disk, where a turn that ended with a message still in Claude's own queue goes
+// on with it; null when it cannot be read.
+export function turnInTranscript(path) {
+    const lines = transcriptTail(path);
+    if (!lines)
+        return null;
+    const turn = lastTurn(lines);
+    return turn?.over && heldByClaude(lines).length ? { over: false } : turn;
+}

package/dist/server/agents/claude/transcript/watch.js

@@ -0,0 +1,60 @@
+import { watch } from 'node:fs';
+import { findTranscript } from './transcriptFile.js';
+// A transcript that is not there yet is looked for this often; a new session writes it with its first message.
+const FIND_MS = 1000;
+// Changes this close together are told once: a reply is often several writes in a row.
+const SETTLE_MS = 100;
+// Calls `changed` whenever the session's transcript is written to, from when it first appears; the function
+// returned stops it. A transcript replaced by a new file (renamed over) is found again, and so is the new
+// one when the session moves to another conversation (`sessionId` is asked again each time).
+export function watchTranscript(root, sessionId, changed) {
+    let stopped = false;
+    let watcher = null;
+    let watching;
+    let timer;
+    let settle;
+    const moved = setInterval(() => watcher && sessionId() !== watching && again(), FIND_MS);
+    const tell = () => {
+        clearTimeout(settle);
+        settle = setTimeout(() => !stopped && changed(), SETTLE_MS);
+    };
+    const find = async () => {
+        const sid = sessionId();
+        const path = sid ? await findTranscript(root, sid).catch(() => null) : null;
+        if (stopped)
+            return;
+        if (!path) {
+            timer = setTimeout(find, FIND_MS);
+            return;
+        }
+        try {
+            watcher = watch(path, (event) => {
+                tell();
+                if (event === 'rename')
+                    again();
+            });
+            watcher.on('error', again);
+            watching = sid;
+        }
+        catch {
+            timer = setTimeout(find, FIND_MS);
+            return;
+        }
+        tell();
+    };
+    const again = () => {
+        watcher?.close();
+        watcher = null;
+        clearTimeout(timer);
+        if (!stopped)
+            timer = setTimeout(find, FIND_MS);
+    };
+    void find();
+    return () => {
+        stopped = true;
+        clearInterval(moved);
+        clearTimeout(timer);
+        clearTimeout(settle);
+        watcher?.close();
+    };
+}

package/dist/server/agents/claude/usage.js

@@ -0,0 +1,36 @@
+const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined);
+const pct = (v) => {
+    const n = num(v);
+    return n === undefined ? undefined : Math.min(100, n);
+};
+const str = (v) => (typeof v === 'string' && v ? v.slice(0, 80) : undefined);
+function limit(v) {
+    const o = obj(v);
+    const used = pct(o?.used_percentage);
+    if (used === undefined)
+        return undefined;
+    // Unix seconds.
+    const resetsAt = num(o?.resets_at);
+    return resetsAt === undefined ? { used } : { used, resetsAt };
+}
+export function usageFrom(payload) {
+    const p = obj(payload);
+    if (!p)
+        return null;
+    const model = obj(p.model);
+    const cost = obj(p.cost);
+    const limits = obj(p.rate_limits);
+    const u = {
+        model: str(model?.display_name) ?? str(model?.id) ?? str(p.model),
+        effort: str(obj(p.effort)?.level),
+        context: pct(obj(p.context_window)?.used_percentage),
+        fiveHour: limit(limits?.five_hour),
+        sevenDay: limit(limits?.seven_day),
+        cost: num(cost?.total_cost_usd),
+        added: num(cost?.total_lines_added),
+        removed: num(cost?.total_lines_removed),
+    };
+    const kept = Object.fromEntries(Object.entries(u).filter(([, v]) => v !== undefined));
+    return Object.keys(kept).length ? kept : null;
+}

package/dist/server/agents/codex/agent.js

@@ -0,0 +1,263 @@
+import { connectAppServer } from './appServer.js';
+import { decisionOf, entriesOf, inputOf } from './items.js';
+import { CodexNotifications } from './notifications.js';
+import { RpcError } from './rpc.js';
+const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : undefined);
+const str = (v) => (typeof v === 'string' ? v : '');
+const ITEMS_PAGE = 200;
+const LIST_MS = 30_000;
+const RETRY_MIN_MS = 1000;
+const RETRY_MAX_MS = 30_000;
+// A thread not written to disk yet (no turn so far) cannot be joined; its first turn writes it.
+const notWrittenYet = (e) => e instanceof RpcError && /no rollout/i.test(e.message);
+// WorkOffDesk's sessions of Codex, as one client of the app server their TUIs run on (docs/design/
+// 2026-10-07-codex-sessions.md): it learns each session's thread, joins it, and turns what the thread does
+// into the session's status, chat, asks and usage; what the phone sends goes to the thread.
+export class CodexAgent {
+    options;
+    host;
+    rpc = null;
+    connecting = null;
+    retryMs = RETRY_MIN_MS;
+    retryAt = 0;
+    closed = false;
+    threads = new Map();
+    bySession = new Map();
+    // What the app server tells of the threads followed, and asks of them.
+    notes;
+    constructor(options, host) {
+        this.options = options;
+        this.host = host;
+        this.notes = new CodexNotifications(host, this.threads, {
+            track: (session, threadId) => this.track(session, threadId),
+            join: (t) => this.join(t),
+            following: (session) => this.bySession.has(session),
+        });
+    }
+    // Before a new session's TUI starts: the app server is running, and the thread it resumes is the
+    // session's. One it starts is found when it does (started).
+    async start(session, resume) {
+        await this.link();
+        if (!resume)
+            return;
+        this.host.setThread(session, resume);
+        this.track(session, resume);
+    }
+    // A session whose thread is known is followed; called on every listing, so a restart picks it up again.
+    follow(session, threadId) {
+        if (threadId && !this.bySession.has(session))
+            this.track(session, threadId);
+        if (!this.rpc?.open && Date.now() >= this.retryAt)
+            void this.link().catch(() => { });
+    }
+    forget(session) {
+        const threadId = this.bySession.get(session);
+        this.bySession.delete(session);
+        if (!threadId)
+            return;
+        const t = this.threads.get(threadId);
+        if (t?.liveTimer)
+            clearTimeout(t.liveTimer);
+        this.threads.delete(threadId);
+        void this.rpc?.request('thread/unsubscribe', { threadId }).catch(() => { });
+    }
+    // The threads people had on this Mac, newest first, as the app server lists them: it reads every session file
+    // to answer, which takes seconds.
+    async listThreads(params) {
+        const { data } = await (await this.link()).request('thread/list', params, LIST_MS);
+        return Array.isArray(data) ? data : [];
+    }
+    // One thread's metadata, read without loading it; undefined when there is no such thread.
+    async readThread(threadId) {
+        const r = await (await this.link()).request('thread/read', { threadId }).catch((e) => {
+            if (e instanceof RpcError && e.code < 0)
+                throw e;
+            return null;
+        });
+        return obj(r?.thread);
+    }
+    // A thread's conversation so far, as the chat shows it, read without loading or joining it.
+    async readItems(threadId) {
+        const rpc = await this.link();
+        const entries = [];
+        let cursor = null;
+        do {
+            const page = await rpc.request('thread/items/list', { threadId, limit: ITEMS_PAGE, ...(cursor && { cursor }) });
+            for (const d of Array.isArray(page.data) ? page.data : []) {
+                const at = obj(d)?.startedAtMs;
+                entries.push(...entriesOf(obj(d)?.item, typeof at === 'number' ? new Date(at).toISOString() : undefined));
+            }
+            cursor = typeof page.nextCursor === 'string' ? page.nextCursor : null;
+        } while (cursor);
+        return entries;
+    }
+    lastReply(session) {
+        return this.threadOf(session)?.said || null;
+    }
+    asks(session) {
+        return [...(this.threadOf(session)?.asks.values() ?? [])].map((a) => a.ask);
+    }
+    answer(session, askId, answer) {
+        const t = this.threadOf(session);
+        const held = t?.asks.get(askId);
+        if (!t || !held || !this.rpc?.respond(held.requestId, decisionOf(held.method, held.params, answer)))
+            return false;
+        t.asks.delete(askId);
+        this.host.asksChanged(session);
+        return true;
+    }
+    // A message for the thread, under the id it was sent with, which comes back on the item it makes. A turn
+    // started while one runs goes into that one.
+    async send(session, text, qid) {
+        const t = this.threadOf(session);
+        if (!t)
+            throw new Error('this Codex session has no thread yet');
+        const rpc = await this.link();
+        try {
+            await rpc.request('turn/start', { threadId: t.threadId, clientUserMessageId: qid, input: inputOf(text) });
+        }
+        catch (e) {
+            // Asked and not answered, it may have gone in: it is not sent again.
+            if (e instanceof RpcError && e.code === RpcError.TIMEOUT)
+                throw Object.assign(e, { mayHaveRun: true });
+            throw e;
+        }
+    }
+    close() {
+        this.closed = true;
+        this.rpc?.close();
+    }
+    threadOf(session) {
+        const id = this.bySession.get(session);
+        return id ? this.threads.get(id) : undefined;
+    }
+    track(session, threadId) {
+        const known = this.threads.get(threadId);
+        if (known)
+            return known;
+        const t = {
+            session,
+            threadId,
+            joined: false,
+            joining: null,
+            // Until the app server says otherwise: a thread runs no turn when it starts. What the session showed
+            // before (a wait read off its TUI's screen) was not the thread's.
+            status: 'idle',
+            compacting: false,
+            asks: new Map(),
+            files: new Map(),
+            live: new Map(),
+            liveTimer: null,
+            said: '',
+        };
+        this.threads.set(threadId, t);
+        this.bySession.set(session, threadId);
+        void this.join(t);
+        return t;
+    }
+    link() {
+        if (this.rpc?.open)
+            return Promise.resolve(this.rpc);
+        this.connecting ??= connectAppServer(this.options)
+            .then((rpc) => {
+            this.rpc = rpc;
+            this.retryMs = RETRY_MIN_MS;
+            rpc.onNotification((n) => this.notes.notified(n));
+            rpc.onRequest((r) => this.notes.requested(r));
+            rpc.onClose(() => this.lost(rpc));
+            for (const t of this.threads.values()) {
+                t.joined = false;
+                void this.join(t);
+            }
+            void this.findStarted(rpc).catch(() => { });
+            return rpc;
+        })
+            .catch((e) => {
+            this.retryAt = Date.now() + this.retryMs;
+            this.retryMs = Math.min(RETRY_MAX_MS, this.retryMs * 2);
+            this.host.log('codex app server unreachable', { error: e instanceof Error ? e.message : String(e) });
+            throw e;
+        })
+            .finally(() => {
+            this.connecting = null;
+        });
+        return this.connecting;
+    }
+    // Threads started while this server was not listening (restarted while a TUI asked trust this folder?),
+    // for the sessions still without one.
+    async findStarted(rpc) {
+        if (!this.host.sessions().some((s) => !s.threadId))
+            return;
+        const { data } = await rpc.request('thread/loaded/list', {});
+        for (const threadId of Array.isArray(data) ? data.map(str) : []) {
+            if (!threadId || this.threads.has(threadId))
+                continue;
+            const { thread } = await rpc.request('thread/read', { threadId });
+            this.notes.started(obj(thread));
+        }
+    }
+    // What the app server held for the phone went with it; the TUIs that were on it are gone too. The next
+    // listing connects again, starting it if need be.
+    lost(rpc) {
+        if (this.rpc !== rpc)
+            return;
+        this.rpc = null;
+        for (const t of this.threads.values()) {
+            t.joined = false;
+            if (t.asks.size) {
+                t.asks.clear();
+                this.host.asksChanged(t.session);
+            }
+        }
+        if (!this.closed)
+            this.host.log('codex app server connection lost', {});
+    }
+    // Joins the thread and takes what it holds so far into the journal. One not written yet is joined after
+    // its first turn starts.
+    join(t) {
+        if (t.joined || !this.rpc?.open)
+            return Promise.resolve();
+        t.joining ??= (async () => {
+            const rpc = this.rpc;
+            try {
+                const r = await rpc.request('thread/resume', { threadId: t.threadId, excludeTurns: true });
+                t.joined = true;
+                t.model = str(r.model) || t.model;
+                t.effort = str(r.reasoningEffort) || t.effort;
+                this.notes.statusIs(t, obj(obj(r.thread)?.status));
+                this.notes.nameIs(t, obj(r.thread)?.name);
+                this.notes.usage(t);
+                await this.backfill(rpc, t);
+            }
+            catch (e) {
+                if (notWrittenYet(e)) {
+                    const thread = obj((await rpc.request('thread/read', { threadId: t.threadId }).catch(() => null))?.thread);
+                    this.notes.ranOn(t, thread);
+                    this.notes.statusIs(t, obj(thread?.status));
+                }
+                else
+                    this.host.log('codex thread not joined', { session: t.session, thread: t.threadId, error: e instanceof Error ? e.message : String(e) });
+            }
+            finally {
+                t.joining = null;
+            }
+        })();
+        return t.joining;
+    }
+    async backfill(rpc, t) {
+        let cursor = null;
+        do {
+            const page = await rpc.request('thread/items/list', { threadId: t.threadId, limit: ITEMS_PAGE, ...(cursor && { cursor }) });
+            const entries = (Array.isArray(page.data) ? page.data : []).flatMap((d) => {
+                const at = obj(d)?.startedAtMs;
+                return entriesOf(obj(d)?.item, typeof at === 'number' ? new Date(at).toISOString() : undefined);
+            });
+            if (entries.length && this.threads.get(t.threadId) === t)
+                this.host.journal.putAgentItems(t.session, t.threadId, entries);
+            const reply = entries.findLast((e) => e.item.k === 'text')?.item;
+            if (reply?.k === 'text')
+                t.said = reply.text;
+            cursor = typeof page.nextCursor === 'string' ? page.nextCursor : null;
+        } while (cursor);
+    }
+}

package/dist/server/agents/codex/appServer.js

@@ -0,0 +1,38 @@
+import { homedir } from 'node:os';
+import { CodexRpc } from './rpc.js';
+// Its own tmux session, so it outlives a restart of this server as the sessions' TUIs do; not named like a
+// session (sessionName.ts), so no listing shows it.
+export const APP_SERVER_TMUX = 'workoffdesk-codex';
+const STARTS_MS = 15_000;
+const LOOK_MS = 250;
+const shq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+// The command a session's terminal runs: Codex's TUI on the shared app server, in the session's folder.
+export function tuiCommand(o) {
+    const resume = o.resume ? ` resume ${shq(o.resume)}` : '';
+    const inner = `${shq(o.codexBin)} --remote ${shq(`unix://${o.sock}`)} -C ${shq(o.cwd)} -c check_for_update_on_startup=false${resume}; exec ${shq(o.shell)} -l`;
+    return `${shq(o.shell)} -lc ${shq(inner)}`;
+}
+// A connection to the app server, started first when nothing answers on its socket. A tmux session left
+// from one that died is ended before another is started.
+export async function connectAppServer(o) {
+    try {
+        return await CodexRpc.connect(o.sock);
+    }
+    catch {
+        // not running; started below
+    }
+    await o.tmux.killSession(APP_SERVER_TMUX);
+    const inner = `exec ${shq(o.codexBin)} app-server --listen ${shq(`unix://${o.sock}`)}`;
+    await o.tmux.newSession(APP_SERVER_TMUX, { cwd: homedir(), command: `${shq(o.shell)} -lc ${shq(inner)}`, env: {} });
+    const until = Date.now() + STARTS_MS;
+    for (;;) {
+        await new Promise((r) => setTimeout(r, LOOK_MS));
+        try {
+            return await CodexRpc.connect(o.sock);
+        }
+        catch (e) {
+            if (Date.now() > until)
+                throw new Error(`the Codex app server did not start: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+}