handmux 0.23.0 → 0.25.0

package/dist/src/codexConversationProjection.js

@@ -0,0 +1,199 @@
+import { codexGoalMessageId, codexItemMessageId } from './codexMessageIdentity.js';
+function textMutation(event) {
+    const id = codexItemMessageId(event.turnId, event.itemId);
+    if (!id)
+        return null;
+    const completed = event.type === 'completed' || event.completed === true;
+    return {
+        operation: 'upsert',
+        mode: event.type === 'delta' ? 'append' : 'replace',
+        message: {
+            id,
+            role: 'assistant',
+            type: 'text',
+            turnId: event.turnId,
+            itemId: event.itemId,
+            text: event.type === 'delta' ? event.delta ?? '' : event.text ?? '',
+            completed,
+            streaming: !completed,
+        },
+    };
+}
+export function projectCodexConversationMutation(event) {
+    if (event.type === 'conversation')
+        return event.mutation;
+    if (event.type === 'started' || event.type === 'snapshot'
+        || event.type === 'delta' || event.type === 'completed') {
+        return textMutation(event);
+    }
+    if (event.type === 'turnCompleted') {
+        return event.turnId ? { operation: 'settleTurn', turnId: event.turnId } : null;
+    }
+    if (event.type === 'goal') {
+        if (['blocked', 'usageLimited', 'budgetLimited', 'complete'].includes(event.goal.status)
+            && !event.turnId)
+            return null;
+        const id = codexGoalMessageId(event.goal, event.event);
+        if (!id)
+            return null;
+        return {
+            operation: 'upsert',
+            mode: 'replace',
+            message: {
+                id,
+                role: 'assistant',
+                type: 'goal',
+                turnId: event.turnId,
+                event: event.event,
+                goal: event.goal,
+                completed: true,
+            },
+        };
+    }
+    // Clearing the current Goal changes session state, not an already recorded conversation card.
+    return null;
+}
+function recordOf(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value ? value : null;
+}
+export function parseCodexConversationMutationValue(value) {
+    const record = recordOf(value);
+    if (!record)
+        return null;
+    if (record.operation === 'settleTurn') {
+        const turnId = nonEmpty(record.turnId);
+        return turnId ? { operation: 'settleTurn', turnId } : null;
+    }
+    if (record.operation !== 'upsert' || !['append', 'replace'].includes(String(record.mode)))
+        return null;
+    const message = recordOf(record.message);
+    if (!message)
+        return null;
+    const id = nonEmpty(message.id);
+    const turnId = nonEmpty(message.turnId);
+    if (!id || message.role !== 'assistant' || typeof message.completed !== 'boolean')
+        return null;
+    if (message.type === 'text') {
+        const itemId = nonEmpty(message.itemId);
+        if (!turnId || !itemId || id !== codexItemMessageId(turnId, itemId)
+            || typeof message.text !== 'string' || typeof message.streaming !== 'boolean')
+            return null;
+        return {
+            operation: 'upsert', mode: record.mode,
+            message: {
+                id, role: 'assistant', type: 'text', turnId, itemId, text: message.text,
+                completed: message.completed, streaming: message.streaming,
+            },
+        };
+    }
+    const goal = recordOf(message.goal);
+    const event = nonEmpty(message.event);
+    const itemId = nonEmpty(message.itemId);
+    const statuses = ['active', 'paused', 'blocked', 'usageLimited', 'budgetLimited', 'complete'];
+    const events = ['set', 'restarted', ...statuses];
+    const objective = nonEmpty(goal?.objective);
+    const numericKeys = ['createdAt', 'updatedAt', 'tokensUsed', 'timeUsedSeconds'];
+    const invalidNumber = numericKeys.some((key) => goal && Object.hasOwn(goal, key)
+        && (typeof goal[key] !== 'number' || !Number.isFinite(goal[key])));
+    const invalidBudget = goal && Object.hasOwn(goal, 'tokenBudget') && goal.tokenBudget !== null
+        && (typeof goal.tokenBudget !== 'number' || !Number.isFinite(goal.tokenBudget));
+    if (message.type !== 'goal' || message.completed !== true || !goal || !objective
+        || !statuses.includes(String(goal.status)) || !event || !events.includes(event)
+        || invalidNumber || invalidBudget
+        || (message.turnId !== null && !turnId)
+        || (id !== codexGoalMessageId(goal, event)
+            && (!turnId || !itemId || id !== codexItemMessageId(turnId, itemId))))
+        return null;
+    return {
+        operation: 'upsert', mode: record.mode,
+        message: {
+            id, role: 'assistant', type: 'goal', turnId: turnId || null, event,
+            goal: goal, completed: true,
+        },
+    };
+}
+// The raw App Server fields remain on the event for compatibility, but consumers only receive this
+// canonical mutation. Reconstructing the mutation from the validated event prevents a forged duplicate
+// payload from smuggling a second identity or lifecycle into the Web projection.
+export function parseCodexConversationMutation(value, event) {
+    const expected = projectCodexConversationMutation(event);
+    if (!expected)
+        return value === null ? null : undefined;
+    const supplied = parseCodexConversationMutationValue(value);
+    if (!supplied)
+        return undefined;
+    if (expected.operation === 'settleTurn') {
+        if (supplied.operation !== 'settleTurn')
+            return undefined;
+        return supplied.turnId === expected.turnId ? expected : undefined;
+    }
+    if (supplied.operation !== 'upsert')
+        return undefined;
+    const message = supplied.message;
+    if (supplied.mode !== expected.mode)
+        return undefined;
+    const projected = expected.message;
+    if (message.id !== projected.id || message.role !== projected.role
+        || message.type !== projected.type || message.turnId !== projected.turnId
+        || message.completed !== projected.completed)
+        return undefined;
+    if (projected.type === 'text') {
+        if (message.type !== 'text')
+            return undefined;
+        if (message.itemId !== projected.itemId || message.text !== projected.text
+            || message.streaming !== projected.streaming)
+            return undefined;
+    }
+    else {
+        if (message.type !== 'goal' || message.event !== projected.event)
+            return undefined;
+    }
+    return expected;
+}
+export function projectCodexRolloutMutation(value) {
+    const message = recordOf(value);
+    const id = nonEmpty(message?.id);
+    if (!message || !id || message.role !== 'assistant')
+        return null;
+    if (message.type === 'text') {
+        const turnId = nonEmpty(message.turnId);
+        const itemId = nonEmpty(message.itemId);
+        if (!turnId || !itemId || typeof message.text !== 'string'
+            || id !== codexItemMessageId(turnId, itemId))
+            return null;
+        return {
+            operation: 'upsert', mode: 'replace',
+            message: {
+                id, role: 'assistant', type: 'text', turnId, itemId, text: message.text,
+                completed: true, streaming: false,
+            },
+        };
+    }
+    if (message.type !== 'goal')
+        return null;
+    const parsed = parseCodexConversationMutationValue({
+        operation: 'upsert', mode: 'replace',
+        message: { ...message, completed: true },
+    });
+    return parsed?.operation === 'upsert' ? parsed : null;
+}
+export function reconcileCodexRolloutMessages(previous, liveMessageIds, messages) {
+    const fingerprints = new Map();
+    const mutations = [];
+    for (const value of messages) {
+        const mutation = projectCodexRolloutMutation(value);
+        if (!mutation || mutation.operation !== 'upsert')
+            continue;
+        const fingerprint = JSON.stringify(mutation.message);
+        fingerprints.set(mutation.message.id, fingerprint);
+        if (liveMessageIds.has(mutation.message.id)
+            && previous.get(mutation.message.id) !== fingerprint)
+            mutations.push(mutation);
+    }
+    return { fingerprints, mutations };
+}

package/dist/src/codexDiff.js

@@ -0,0 +1,118 @@
+const HUNK_HEADER = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+function changedLines(lines) {
+    return lines.filter((line) => /^[+-]/.test(line)
+        && !line.startsWith('+++') && !line.startsWith('---'));
+}
+export function parseUnifiedDiff(value, { created = false } = {}) {
+    const lines = String(value || '').split('\n');
+    let added = 0;
+    let removed = 0;
+    const hunks = [];
+    let current = null;
+    const flush = () => {
+        if (current?.lines.length)
+            hunks.push(current);
+        current = null;
+    };
+    for (const line of lines) {
+        const header = HUNK_HEADER.exec(line);
+        if (header) {
+            flush();
+            current = { oldStart: Number(header[1]), newStart: Number(header[2]), lines: [] };
+            continue;
+        }
+        if (line.startsWith('+') && !line.startsWith('+++'))
+            added++;
+        else if (line.startsWith('-') && !line.startsWith('---'))
+            removed++;
+        if (current && /^[ +\-]/.test(line) && !line.startsWith('+++') && !line.startsWith('---')) {
+            current.lines.push(line);
+        }
+    }
+    flush();
+    return {
+        added,
+        removed,
+        hunks: hunks.length ? hunks : null,
+        ...(created ? { created: true } : {}),
+    };
+}
+function applyPatchSection(value, path) {
+    const lines = String(value || '').split('\n');
+    let active = false;
+    const section = [];
+    for (const line of lines) {
+        const header = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/.exec(line);
+        if (header) {
+            if (active)
+                break;
+            active = (header[1] ?? '').trim() === path;
+            continue;
+        }
+        if (active && line === '*** End Patch')
+            break;
+        if (active)
+            section.push(line);
+    }
+    return section;
+}
+function diffKey(lines) {
+    return changedLines(lines).join('\0');
+}
+function sameFilePath(left, right) {
+    const a = String(left || '').replaceAll('\\', '/').replace(/^\.\//, '');
+    const b = String(right || '').replaceAll('\\', '/').replace(/^\.\//, '');
+    return a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`);
+}
+function candidateDiffs(thread) {
+    const candidates = [];
+    for (const turn of thread?.turns || []) {
+        for (const item of turn?.items || []) {
+            if (item?.type !== 'fileChange')
+                continue;
+            for (const change of item.changes || []) {
+                const diff = parseUnifiedDiff(change?.diff, { created: change?.kind?.type === 'add' });
+                if (!diff.hunks)
+                    continue;
+                candidates.push({
+                    turnId: typeof turn.id === 'string' && turn.id ? turn.id : null,
+                    path: typeof change?.path === 'string' ? change.path : '',
+                    key: diffKey(String(change?.diff || '').split('\n')),
+                    diff,
+                });
+            }
+        }
+    }
+    return candidates;
+}
+export function enrichCodexFileDiffs(messages, thread) {
+    const candidates = candidateDiffs(thread);
+    const used = new Set();
+    return messages.map((message) => {
+        const tool = message?.tool;
+        const positioned = tool?.diff?.hunks?.length
+            && tool.diff.hunks.every((hunk) => Number.isInteger(hunk.oldStart) && Number.isInteger(hunk.newStart));
+        if (tool?.name !== 'apply_patch' || !tool.diff || positioned)
+            return message;
+        const targetDiff = tool.diff;
+        const input = Array.isArray(tool.input) ? null : tool.input;
+        const path = typeof input?.file_path === 'string' ? input.file_path : '';
+        const key = diffKey(applyPatchSection(input?.patch, path));
+        const matches = (candidate, index) => !used.has(index)
+            && sameFilePath(candidate.path, path)
+            && candidate.diff.added === targetDiff.added
+            && candidate.diff.removed === targetDiff.removed
+            && (!message.turnId || !candidate.turnId || candidate.turnId === message.turnId);
+        let index = candidates.findIndex((candidate, candidateIndex) => matches(candidate, candidateIndex)
+            && (!key || !candidate.key || candidate.key === key));
+        if (index < 0 && !key)
+            index = candidates.findIndex(matches);
+        if (index < 0)
+            return message;
+        const candidate = candidates[index];
+        if (!candidate)
+            return message;
+        used.add(index);
+        return { ...message, tool: { ...tool, diff: candidate.diff } };
+    });
+}

package/dist/src/codexMessageIdentity.js

@@ -0,0 +1,18 @@
+function nonEmpty(value) {
+    return typeof value === 'string' && value ? value : null;
+}
+export function codexItemMessageId(turnId, itemId, child = null) {
+    const turn = nonEmpty(turnId);
+    const item = nonEmpty(itemId);
+    if (!turn || !item)
+        return null;
+    const base = `codex:${turn}:${item}`;
+    return child == null ? base : `${base}:child-${encodeURIComponent(String(child))}`;
+}
+export function codexGoalMessageId(goal, event) {
+    const lifecycle = nonEmpty(event) || nonEmpty(goal?.status);
+    const marker = goal?.createdAt ?? goal?.updatedAt ?? nonEmpty(goal?.objective);
+    if (!lifecycle || marker == null)
+        return null;
+    return `codex-goal:${encodeURIComponent(String(marker))}:${encodeURIComponent(lifecycle)}`;
+}

package/dist/src/codexPlan.js

@@ -0,0 +1,30 @@
+const PLAN_STATUSES = new Map([
+    ['pending', 'pending'],
+    ['inProgress', 'inProgress'],
+    ['in_progress', 'inProgress'],
+    ['completed', 'completed'],
+]);
+// Keep plan projection deliberately small and text-only. App Server uses camelCase statuses while the
+// persisted Code Mode call uses snake_case; the phone receives one stable shape from either source.
+export function normalizeCodexPlan(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.slice(0, 100).flatMap((item) => {
+        const record = item && typeof item === 'object' ? item : null;
+        const step = typeof record?.step === 'string' ? record.step.trim().slice(0, 2_000) : '';
+        const status = typeof record?.status === 'string' ? PLAN_STATUSES.get(record.status) : undefined;
+        return step && status ? [{ step, status }] : [];
+    });
+}
+export function codexPlanSnapshot(turnId, value, explanation = null) {
+    const steps = normalizeCodexPlan(value);
+    if (!turnId || !steps?.length)
+        return null;
+    return {
+        turnId,
+        steps,
+        ...(typeof explanation === 'string' && explanation.trim()
+            ? { explanation: explanation.trim().slice(0, 4_000) }
+            : {}),
+    };
+}

package/dist/src/codexQueueProtocol.js

@@ -0,0 +1,137 @@
+function recordOf(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringOf(value) {
+    return typeof value === 'string' && value ? value : null;
+}
+function timeOf(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+export function parseCodexQueueItem(value) {
+    const record = recordOf(value);
+    if (!record)
+        return null;
+    const id = stringOf(record.id);
+    const text = stringOf(record.text);
+    const createdAt = timeOf(record.createdAt);
+    if (!id || !text || createdAt == null)
+        return null;
+    const requestId = record.requestId == null ? undefined : stringOf(record.requestId) ?? undefined;
+    if (record.requestId != null && !requestId)
+        return null;
+    if (record.editing != null && record.editing !== true)
+        return null;
+    return {
+        ...record, id, text, createdAt,
+        ...(requestId ? { requestId } : {}),
+        ...(record.editing === true ? { editing: true } : {}),
+    };
+}
+export function parseCodexSendResult(value) {
+    const record = recordOf(value);
+    if (!record)
+        return null;
+    if (record.queued === true) {
+        const item = parseCodexQueueItem(record.item);
+        return item ? { ...record, queued: true, item } : null;
+    }
+    if (record.queued != null && record.queued !== false)
+        return null;
+    const turn = record.turn == null ? record.turn : recordOf(record.turn);
+    if (record.turn != null && !turn)
+        return null;
+    if (turn?.id != null && typeof turn.id !== 'string')
+        return null;
+    return { ...record, ...(record.queued === false ? { queued: false } : {}), ...(turn ? { turn } : {}) };
+}
+export function parseCodexSubmissionReceipt(value) {
+    const record = recordOf(value);
+    if (!record)
+        return null;
+    const pane = stringOf(record.pane);
+    const threadId = stringOf(record.threadId);
+    const requestId = stringOf(record.requestId);
+    const text = stringOf(record.text);
+    const statuses = ['pending', 'queued', 'accepted'];
+    const status = statuses.find((candidate) => candidate === record.status);
+    const createdAt = timeOf(record.createdAt);
+    const updatedAt = timeOf(record.updatedAt);
+    if (!pane || !threadId || !requestId || !text || !status || createdAt == null || updatedAt == null)
+        return null;
+    const queueItemId = record.queueItemId == null ? undefined : stringOf(record.queueItemId) ?? undefined;
+    const turnId = record.turnId == null ? undefined : stringOf(record.turnId) ?? undefined;
+    if ((record.queueItemId != null && !queueItemId) || (record.turnId != null && !turnId))
+        return null;
+    if (status === 'queued' && !queueItemId)
+        return null;
+    return {
+        pane, threadId, requestId, text, status, createdAt, updatedAt,
+        ...(queueItemId ? { queueItemId } : {}),
+        ...(turnId ? { turnId } : {}),
+    };
+}
+export function parseCodexSubmissionReceiptView(value) {
+    const record = recordOf(value);
+    if (!record)
+        return null;
+    const requestId = stringOf(record.requestId);
+    const statuses = ['pending', 'queued', 'accepted'];
+    const status = statuses.find((candidate) => candidate === record.status);
+    const queueItemId = record.queueItemId == null ? undefined : stringOf(record.queueItemId) ?? undefined;
+    const turnId = record.turnId == null ? undefined : stringOf(record.turnId) ?? undefined;
+    if (!requestId || !status
+        || (record.queueItemId != null && !queueItemId)
+        || (record.turnId != null && !turnId)
+        || (status === 'queued' && !queueItemId))
+        return null;
+    return {
+        requestId, status,
+        ...(queueItemId ? { queueItemId } : {}),
+        ...(turnId ? { turnId } : {}),
+    };
+}
+export function parseCodexOutboxSnapshot(value) {
+    const record = recordOf(value);
+    if (!record || record.version !== 1 || !Array.isArray(record.queues) || !Array.isArray(record.receipts)) {
+        return null;
+    }
+    const queues = [];
+    const queueKeys = new Set();
+    for (const candidate of record.queues) {
+        const queue = recordOf(candidate);
+        if (!queue || !Array.isArray(queue.items))
+            return null;
+        const pane = stringOf(queue.pane);
+        const threadId = stringOf(queue.threadId);
+        const items = queue.items.map(parseCodexQueueItem);
+        if (!pane || !threadId || items.some((item) => !item))
+            return null;
+        const queueKey = `${pane}\0${threadId}`;
+        if (queueKeys.has(queueKey))
+            return null;
+        queueKeys.add(queueKey);
+        const itemIds = new Set();
+        const itemRequestIds = new Set();
+        for (const item of items) {
+            if (itemIds.has(item.id) || (item.requestId && itemRequestIds.has(item.requestId)))
+                return null;
+            itemIds.add(item.id);
+            if (item.requestId)
+                itemRequestIds.add(item.requestId);
+        }
+        queues.push({ pane, threadId, items: items });
+    }
+    const receipts = record.receipts.map(parseCodexSubmissionReceipt);
+    if (receipts.some((receipt) => !receipt))
+        return null;
+    const receiptKeys = new Set();
+    for (const receipt of receipts) {
+        const receiptKey = `${receipt.pane}\0${receipt.threadId}\0${receipt.requestId}`;
+        if (receiptKeys.has(receiptKey))
+            return null;
+        receiptKeys.add(receiptKey);
+    }
+    return { version: 1, queues, receipts: receipts };
+}