specrails-desktop 2.0.0

package/server/dist/rails-router.js

@@ -0,0 +1,362 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRailsRouter = createRailsRouter;
+const express_1 = require("express");
+const rails_store_1 = require("./rails-store");
+const queue_manager_1 = require("./queue-manager");
+const provider_selection_1 = require("./provider-selection");
+const VALID_MODES = new Set(['implement', 'batch-implement', 'ultracode']);
+// Models the ultracode picker exposes (Claude aliases). Mirrors the client
+// RailModelSelector options and the project-router orchestrator-model allow-list.
+const VALID_ULTRACODE_MODELS = new Set(['haiku', 'sonnet', 'opus']);
+function createRailsRouter() {
+    const router = (0, express_1.Router)({ mergeParams: true });
+    function ctx(req) {
+        return req.projectCtx;
+    }
+    // Broadcast the full post-mutation rail snapshot so every connected client
+    // (desktop dashboard + mobile companion) reflects non-launch rail changes
+    // live — ticket reassignments, renames, mode/profile/engine edits. Re-reads
+    // the canonical rail (getRail) so the snapshot always carries the CURRENT
+    // name — a mutation return value (e.g. setRailTickets) omits it, which would
+    // otherwise broadcast name:null and clobber the rail's label on receivers.
+    function broadcastRailUpdated(c, railIndex, changed) {
+        const rail = (0, rails_store_1.getRail)(c.db, railIndex);
+        const msg = {
+            type: 'rail.updated',
+            projectId: c.project.id,
+            railIndex: rail.railIndex,
+            changed,
+            ticketIds: rail.ticketIds,
+            name: rail.name ?? null,
+            mode: rail.mode,
+            profileName: rail.profileName ?? null,
+            aiEngine: rail.aiEngine ?? null,
+        };
+        c.broadcast(msg);
+    }
+    // GET /rails — list all rail assignments + active job info
+    router.get('/', (_req, res) => {
+        const c = ctx(_req);
+        try {
+            const rails = (0, rails_store_1.getRails)(c.db);
+            // Include which rails have active jobs (so clients can reconcile stale 'running' state)
+            const activeJobs = {};
+            for (const [jobId, meta] of c.railJobs.entries()) {
+                activeJobs[meta.railIndex] = { jobId, mode: meta.mode };
+            }
+            res.json({ rails, activeJobs });
+        }
+        catch (err) {
+            console.error('[rails-router] get rails error:', err);
+            res.status(500).json({ error: 'Failed to fetch rails' });
+        }
+    });
+    // PUT /rails/:railIndex/tickets — set ticket assignments for a rail
+    router.put('/:railIndex/tickets', (req, res) => {
+        const railIndex = parseInt(req.params.railIndex, 10);
+        if (isNaN(railIndex) || railIndex < 0) {
+            res.status(400).json({ error: 'Invalid rail index' });
+            return;
+        }
+        const { ticketIds } = req.body ?? {};
+        if (!Array.isArray(ticketIds) || ticketIds.some((id) => typeof id !== 'number')) {
+            res.status(400).json({ error: 'ticketIds must be an array of numbers' });
+            return;
+        }
+        const c = ctx(req);
+        try {
+            // setRailTickets does delete-then-reinsert; without forwarding the rail's
+            // current mode/profileName they would reset to defaults ('implement' /
+            // null) on every ticket reassignment, silently wiping a configured
+            // per-rail profile. Preserve them (an explicit body value still wins).
+            const current = (0, rails_store_1.getRail)(c.db, railIndex);
+            const body = req.body ?? {};
+            const mode = typeof body.mode === 'string' ? body.mode : current.mode;
+            const profileName = 'profileName' in body ? body.profileName : current.profileName;
+            // Preserve the rail's AI engine across ticket reassignment (undefined →
+            // setRailTickets re-reads the current value), so it isn't silently wiped.
+            const aiEngine = 'aiEngine' in body ? body.aiEngine : undefined;
+            const rail = (0, rails_store_1.setRailTickets)(c.db, railIndex, ticketIds, mode, profileName, aiEngine);
+            broadcastRailUpdated(c, railIndex, 'tickets');
+            res.json({ rail });
+        }
+        catch (err) {
+            console.error('[rails-router] set rail tickets error:', err);
+            res.status(500).json({ error: 'Failed to update rail tickets' });
+        }
+    });
+    // PUT /rails/:railIndex/profile — set the default agent profile for a rail
+    // Body: { profileName: string | null } (null = force legacy mode for this rail)
+    router.put('/:railIndex/profile', (req, res) => {
+        const railIndex = parseInt(req.params.railIndex, 10);
+        if (isNaN(railIndex) || railIndex < 0) {
+            res.status(400).json({ error: 'Invalid rail index' });
+            return;
+        }
+        const body = req.body ?? {};
+        if (!('profileName' in body)) {
+            res.status(400).json({ error: "body must include 'profileName' (string or null)" });
+            return;
+        }
+        const value = body.profileName;
+        if (value !== null && typeof value !== 'string') {
+            res.status(400).json({ error: 'profileName must be a string or null' });
+            return;
+        }
+        const c = ctx(req);
+        try {
+            const rail = (0, rails_store_1.setRailProfile)(c.db, railIndex, value);
+            broadcastRailUpdated(c, railIndex, 'profile');
+            res.json({ rail });
+        }
+        catch (err) {
+            console.error('[rails-router] set rail profile error:', err);
+            res.status(500).json({ error: 'Failed to update rail profile' });
+        }
+    });
+    // PUT /rails/:railIndex/engine — set the AI engine override for a rail
+    // Body: { aiEngine: string | null } (null = use the project's primary provider)
+    router.put('/:railIndex/engine', (req, res) => {
+        const railIndex = parseInt(req.params.railIndex, 10);
+        if (isNaN(railIndex) || railIndex < 0) {
+            res.status(400).json({ error: 'Invalid rail index' });
+            return;
+        }
+        const body = req.body ?? {};
+        if (!('aiEngine' in body)) {
+            res.status(400).json({ error: "body must include 'aiEngine' (string or null)" });
+            return;
+        }
+        const value = body.aiEngine;
+        const c = ctx(req);
+        // null clears the override; a string must be one of the project's providers.
+        if (value !== null) {
+            const check = (0, provider_selection_1.validateRequestedProvider)(c.project, value);
+            if (!check.ok) {
+                res.status(400).json({ error: check.error });
+                return;
+            }
+        }
+        try {
+            const rail = (0, rails_store_1.setRailEngine)(c.db, railIndex, value);
+            broadcastRailUpdated(c, railIndex, 'engine');
+            res.json({ rail });
+        }
+        catch (err) {
+            console.error('[rails-router] set rail engine error:', err);
+            res.status(500).json({ error: 'Failed to update rail engine' });
+        }
+    });
+    // PUT /rails/:railIndex/name — set the rail's display name (the "Rail "-suffix)
+    // Body: { name: string | null } (empty/null clears it back to the default label)
+    router.put('/:railIndex/name', (req, res) => {
+        const railIndex = parseInt(req.params.railIndex, 10);
+        if (isNaN(railIndex) || railIndex < 0) {
+            res.status(400).json({ error: 'Invalid rail index' });
+            return;
+        }
+        const body = req.body ?? {};
+        if (!('name' in body)) {
+            res.status(400).json({ error: "body must include 'name' (string or null)" });
+            return;
+        }
+        const value = body.name;
+        if (value !== null && typeof value !== 'string') {
+            res.status(400).json({ error: 'name must be a string or null' });
+            return;
+        }
+        // Guard against unbounded labels (UI shows a short chip).
+        if (typeof value === 'string' && value.length > 60) {
+            res.status(400).json({ error: 'name must be 60 characters or fewer' });
+            return;
+        }
+        const c = ctx(req);
+        try {
+            const rail = (0, rails_store_1.setRailName)(c.db, railIndex, value);
+            broadcastRailUpdated(c, railIndex, 'name');
+            res.json({ rail });
+        }
+        catch (err) {
+            console.error('[rails-router] set rail name error:', err);
+            res.status(500).json({ error: 'Failed to update rail name' });
+        }
+    });
+    // POST /rails/:railIndex/launch — launch job(s) for a rail
+    router.post('/:railIndex/launch', (req, res) => {
+        const railIndex = parseInt(req.params.railIndex, 10);
+        if (isNaN(railIndex) || railIndex < 0) {
+            res.status(400).json({ error: 'Invalid rail index' });
+            return;
+        }
+        const { mode = 'implement', profileName, aiEngine, model } = req.body ?? {};
+        if (!VALID_MODES.has(mode)) {
+            res.status(400).json({ error: 'mode must be "implement", "batch-implement" or "ultracode"' });
+            return;
+        }
+        // Ultracode model picker: optional, validated against the allow-list.
+        // Ignored for non-ultracode modes (they use the orchestrator model).
+        if (mode === 'ultracode' && model !== undefined && model !== null) {
+            if (typeof model !== 'string' || !VALID_ULTRACODE_MODELS.has(model)) {
+                res.status(400).json({ error: 'model must be one of: haiku, sonnet, opus' });
+                return;
+            }
+        }
+        const c = ctx(req);
+        const rail = (0, rails_store_1.getRail)(c.db, railIndex);
+        if (rail.ticketIds.length === 0) {
+            res.status(400).json({ error: 'Rail has no tickets assigned' });
+            return;
+        }
+        // AI engine precedence: explicit body param > stored rail engine > primary.
+        // `undefined`/empty in both means "run on the project's primary provider".
+        const requestedEngine = aiEngine === undefined ? (rail.aiEngine ?? undefined) : aiEngine;
+        const engineCheck = (0, provider_selection_1.validateRequestedProvider)(c.project, requestedEngine);
+        if (!engineCheck.ok) {
+            res.status(400).json({ error: engineCheck.error });
+            return;
+        }
+        // Only pass a provider override when one was actually requested (keeps
+        // single-provider rails on the legacy code path).
+        const railProvider = requestedEngine ? engineCheck.provider : undefined;
+        // Ultracode bypasses the OpenSpec pipeline and hands the raw spec to
+        // Claude. It is Claude-only — reject when the effective engine is not claude.
+        if (mode === 'ultracode' && engineCheck.provider !== 'claude') {
+            res.status(400).json({ error: 'Ultracode requires the Claude provider' });
+            return;
+        }
+        // Profile selection precedence: explicit body param > stored rail profile > default resolution.
+        // `null` in the body explicitly forces legacy mode. Codex has no agent
+        // profiles, so force legacy mode whenever the chosen engine is not claude.
+        let resolvedProfile;
+        if (mode === 'ultracode') {
+            // Ultracode runs no agent pipeline, so profiles do not apply.
+            resolvedProfile = null;
+        }
+        else if (railProvider && railProvider !== 'claude') {
+            resolvedProfile = null;
+        }
+        else if (profileName === null) {
+            resolvedProfile = null;
+        }
+        else if (typeof profileName === 'string' && profileName.trim()) {
+            resolvedProfile = profileName.trim();
+        }
+        else if (rail.profileName) {
+            resolvedProfile = rail.profileName;
+        }
+        else {
+            resolvedProfile = undefined; // fall through to QueueManager default resolution
+        }
+        try {
+            let jobId;
+            if (mode === 'ultracode') {
+                // Ultracode launches ONE independent Claude job per ticket — each gets
+                // its own log and runs the spec autonomously (no pipeline). The rail UI
+                // tracks the first job as its representative active job; every job is
+                // registered so its ticket is marked done on completion.
+                // `provider: 'claude'` is explicit so the spawn resolves the claude
+                // adapter regardless of the project's primary.
+                const ultracodeModel = mode === 'ultracode' && typeof model === 'string' && VALID_ULTRACODE_MODELS.has(model)
+                    ? model
+                    : undefined;
+                const jobIds = [];
+                for (const ticketId of rail.ticketIds) {
+                    const command = `/specrails:ultracode #${ticketId} --yes`;
+                    const job = c.queueManager.enqueue(command, 'normal', {
+                        profileName: null,
+                        provider: 'claude',
+                        ...(ultracodeModel ? { model: ultracodeModel } : {}),
+                    });
+                    jobIds.push(job.id);
+                    c.railJobs.set(job.id, { railIndex, mode, ticketIds: [ticketId] });
+                }
+                jobId = jobIds[0];
+                const startMsg = {
+                    type: 'rail.job_started',
+                    projectId: c.project.id,
+                    railIndex,
+                    jobId,
+                    mode,
+                };
+                c.broadcast(startMsg);
+                res.status(202).json({ jobId, jobIds, railIndex, mode });
+                return;
+            }
+            // Implement / batch-implement create a single job with all ticket IDs.
+            // /specrails:implement handles multiple specs in parallel internally.
+            const issueArgs = rail.ticketIds.map((id) => `#${id}`).join(' ');
+            const commandName = mode === 'batch-implement' ? 'batch-implement' : 'implement';
+            const command = `/specrails:${commandName} ${issueArgs} --yes`;
+            const job = c.queueManager.enqueue(command, 'normal', { profileName: resolvedProfile, provider: railProvider });
+            jobId = job.id;
+            c.railJobs.set(jobId, { railIndex, mode, ticketIds: [...rail.ticketIds] });
+            const startMsg = {
+                type: 'rail.job_started',
+                projectId: c.project.id,
+                railIndex,
+                jobId,
+                mode,
+            };
+            c.broadcast(startMsg);
+            res.status(202).json({ jobId, railIndex, mode });
+        }
+        catch (err) {
+            if (err instanceof queue_manager_1.ClaudeNotFoundError) {
+                res.status(503).json({ error: 'Claude CLI not found' });
+                return;
+            }
+            if (err instanceof queue_manager_1.CodexNotFoundError) {
+                res.status(503).json({ error: 'Codex CLI not found' });
+                return;
+            }
+            console.error('[rails-router] launch error:', err);
+            res.status(500).json({ error: 'Failed to launch rail job' });
+        }
+    });
+    // POST /rails/:railIndex/stop — kill the running job for a rail
+    router.post('/:railIndex/stop', (req, res) => {
+        const railIndex = parseInt(req.params.railIndex, 10);
+        if (isNaN(railIndex) || railIndex < 0) {
+            res.status(400).json({ error: 'Invalid rail index' });
+            return;
+        }
+        const c = ctx(req);
+        // M19: an Ultracode rail registers ONE queue job per ticket. The old code
+        // stopped only the FIRST matching job, so the remaining N-1 jobs kept running
+        // and billing while the UI showed the rail stopped. Collect ALL jobs for this
+        // rail index and cancel each (running → kill, queued → cancel).
+        const targetJobIds = Array.from(c.railJobs.entries())
+            .filter(([, meta]) => meta.railIndex === railIndex)
+            .map(([jobId]) => jobId);
+        if (targetJobIds.length === 0) {
+            res.status(404).json({ error: 'No active rail job found for this rail' });
+            return;
+        }
+        let canceledCount = 0;
+        for (const jobId of targetJobIds) {
+            try {
+                c.queueManager.cancel(jobId);
+                canceledCount++;
+            }
+            catch (err) {
+                // Already terminal / unknown — clean up the stale entry regardless so the
+                // rail card can't get wedged 'running' (this was the unrecoverable case).
+                console.warn(`[rails-router] stop: cancel(${jobId}) failed: ${err.message}`);
+            }
+            c.railJobs.delete(jobId);
+        }
+        // Broadcast one stop per job so every rail card reconciles.
+        for (const jobId of targetJobIds) {
+            const stopMsg = {
+                type: 'rail.job_stopped',
+                projectId: c.project.id,
+                railIndex,
+                jobId,
+            };
+            c.broadcast(stopMsg);
+        }
+        res.json({ ok: true, jobIds: targetJobIds, canceled: canceledCount });
+    });
+    return router;
+}

package/server/dist/rails-store.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRails = getRails;
+exports.getRail = getRail;
+exports.setRailTickets = setRailTickets;
+exports.setRailProfile = setRailProfile;
+exports.setRailEngine = setRailEngine;
+exports.setRailName = setRailName;
+/** Read the per-rail display names from rail_meta into a lookup map. */
+function railNames(db) {
+    const rows = db.prepare('SELECT rail_index, name FROM rail_meta').all();
+    const map = new Map();
+    for (const r of rows)
+        map.set(r.rail_index, r.name);
+    return map;
+}
+// ─── Queries ─────────────────────────────────────────────────────────────────
+function getRails(db) {
+    const rows = db
+        .prepare('SELECT rail_index, ticket_id, position, mode, profile_name, ai_engine FROM rails ORDER BY rail_index, position')
+        .all();
+    const map = new Map();
+    for (const row of rows) {
+        if (!map.has(row.rail_index)) {
+            map.set(row.rail_index, {
+                ticketIds: [],
+                mode: row.mode,
+                profileName: row.profile_name,
+                aiEngine: row.ai_engine,
+            });
+        }
+        map.get(row.rail_index).ticketIds.push(row.ticket_id);
+    }
+    const names = railNames(db);
+    return [0, 1, 2].map((railIndex) => {
+        const rail = map.get(railIndex);
+        return {
+            railIndex,
+            ticketIds: rail?.ticketIds ?? [],
+            mode: rail?.mode ?? 'implement',
+            profileName: rail?.profileName ?? null,
+            aiEngine: rail?.aiEngine ?? null,
+            name: names.get(railIndex) ?? null,
+        };
+    });
+}
+function getRail(db, railIndex) {
+    const rows = db
+        .prepare('SELECT ticket_id, position, mode, profile_name, ai_engine FROM rails WHERE rail_index = ? ORDER BY position')
+        .all(railIndex);
+    const meta = db.prepare('SELECT name FROM rail_meta WHERE rail_index = ?').get(railIndex);
+    return {
+        railIndex,
+        ticketIds: rows.map((r) => r.ticket_id),
+        mode: rows[0]?.mode ?? 'implement',
+        profileName: rows[0]?.profile_name ?? null,
+        aiEngine: rows[0]?.ai_engine ?? null,
+        name: meta?.name ?? null,
+    };
+}
+// ─── Mutations ────────────────────────────────────────────────────────────────
+function setRailTickets(db, railIndex, ticketIds, mode, profileName, aiEngine) {
+    const deleteStmt = db.prepare('DELETE FROM rails WHERE rail_index = ?');
+    const insertStmt = db.prepare('INSERT INTO rails (rail_index, ticket_id, position, mode, profile_name, ai_engine) VALUES (?, ?, ?, ?, ?, ?)');
+    const resolvedMode = mode ?? 'implement';
+    const resolvedProfile = profileName === undefined ? null : profileName;
+    // undefined → preserve existing engine across re-orders; null → explicit clear.
+    const resolvedEngine = aiEngine === undefined ? (getRail(db, railIndex).aiEngine ?? null) : aiEngine;
+    db.transaction(() => {
+        deleteStmt.run(railIndex);
+        for (let i = 0; i < ticketIds.length; i++) {
+            insertStmt.run(railIndex, ticketIds[i], i, resolvedMode, resolvedProfile, resolvedEngine);
+        }
+    })();
+    return { railIndex, ticketIds, mode: resolvedMode, profileName: resolvedProfile, aiEngine: resolvedEngine };
+}
+/**
+ * Update only the profile for a rail, preserving tickets and mode.
+ * No-op (returns current state) when the rail has no tickets yet — the
+ * profile is stored as a column on each rail row.
+ */
+function setRailProfile(db, railIndex, profileName) {
+    const current = getRail(db, railIndex);
+    if (current.ticketIds.length === 0) {
+        // No rows to update; insert a placeholder row? No — we store profile on
+        // each ticket row. Users must assign tickets first. Caller checks.
+        return { ...current, profileName };
+    }
+    db.prepare('UPDATE rails SET profile_name = ? WHERE rail_index = ?').run(profileName, railIndex);
+    return { ...current, profileName };
+}
+/**
+ * Update only the AI engine for a rail, preserving tickets, mode and profile.
+ * Like setRailProfile, no-op (returns current state with the new engine) when
+ * the rail has no tickets yet — the engine is stored on each rail row.
+ */
+function setRailEngine(db, railIndex, aiEngine) {
+    const current = getRail(db, railIndex);
+    if (current.ticketIds.length === 0) {
+        return { ...current, aiEngine };
+    }
+    db.prepare('UPDATE rails SET ai_engine = ? WHERE rail_index = ?').run(aiEngine, railIndex);
+    return { ...current, aiEngine };
+}
+/**
+ * Set a rail's display name (the "Rail "-suffix the user types). Stored in
+ * rail_meta (ticket-independent) so even an empty rail keeps its name. Pass
+ * an empty/whitespace name to clear it back to the default "Rail N" label.
+ */
+function setRailName(db, railIndex, name) {
+    const trimmed = typeof name === 'string' ? name.trim() : null;
+    const value = trimmed && trimmed.length > 0 ? trimmed : null;
+    db.prepare(`INSERT INTO rail_meta (rail_index, name) VALUES (?, ?)
+     ON CONFLICT(rail_index) DO UPDATE SET name = excluded.name`).run(railIndex, value);
+    return { ...getRail(db, railIndex), name: value };
+}

package/server/dist/result-event.js

@@ -0,0 +1,106 @@
+"use strict";
+// Result-event normalisation and finalisation for AI CLI invocations.
+//
+// Two coexisting APIs during the multi-provider migration window:
+//
+//   - finaliseInvocationResult(adapter, events, opts) — new contract used by
+//     post-adapter managers. Walks an AdapterEvent stream, calls
+//     `adapter.extractResult`, and falls back to the local pricing table when
+//     the adapter declares `capabilities.nativeCostUsd === false`. Returns
+//     both the NormalisedResult and an `estimated` flag for the
+//     `total_cost_usd_estimated` DB column.
+//
+//   - normaliseResultEvent(event, provider) — legacy single-event shape kept
+//     so non-migrated managers (queue-manager, chat-manager,
+//     agent-refine-manager pre-refactor) keep working. Will be removed after
+//     all callsites migrate (tasks §7–10).
+//
+// Spec: openspec/specs/multi-provider-architecture/spec.md
+// Spec: openspec/changes/add-multi-provider-support/specs/project-spending/spec.md
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.finaliseInvocationResult = finaliseInvocationResult;
+exports.normaliseResultEvent = normaliseResultEvent;
+const pricing_1 = require("./pricing");
+/**
+ * Finalise an AI invocation by walking the adapter's parsed events, stamping
+ * the model when the adapter does not report one, and applying the local
+ * pricing-table fallback when the adapter does not report `total_cost_usd`.
+ */
+function finaliseInvocationResult(adapter, events, opts = {}) {
+    const result = adapter.extractResult(events);
+    const cloned = { ...result };
+    // Stamp the model from the caller when the adapter did not derive one. The
+    // adapter contract permits leaving `model` undefined; the manager knows the
+    // model it spawned with.
+    if (!cloned.model && opts.fallbackModel) {
+        cloned.model = opts.fallbackModel;
+    }
+    let estimated = false;
+    if (!adapter.capabilities.nativeCostUsd) {
+        const estimator = opts.estimator ?? pricing_1.estimateCostUsd;
+        const computed = estimator(adapter.id, cloned.model, {
+            tokens_in: cloned.tokens_in,
+            tokens_out: cloned.tokens_out,
+            tokens_cache_read: cloned.tokens_cache_read,
+            tokens_cache_create: cloned.tokens_cache_create,
+        });
+        if (computed !== null) {
+            cloned.total_cost_usd = computed;
+            estimated = true;
+        }
+        else if (cloned.model) {
+            // Non-native-cost provider with a known model id but no pricing-table
+            // entry → cost is persisted NULL and silently vanishes from totals.
+            // Surface it so a new/renamed/drifted model id is caught fast (the fix
+            // is to add the rate to server/pricing.ts, per its quarterly-review
+            // contract). We deliberately do NOT fabricate a fallback rate.
+            console.warn(`[pricing] no rate-card entry for "${adapter.id}:${cloned.model}" — ` +
+                `cost will be persisted NULL. Add it to server/pricing.ts PRICING.`);
+        }
+    }
+    return { result: cloned, estimated };
+}
+// ─── Legacy single-event API ─────────────────────────────────────────────────
+//
+// Pre-adapter managers still call this with the single terminal event payload
+// they captured. Behaviour identical to the implementation that lived here
+// before; provider-specific branches preserved. Once all callsites migrate to
+// `finaliseInvocationResult`, delete this and remove the import.
+function normaliseResultEvent(event, provider = 'claude') {
+    if (!event)
+        return {};
+    if (provider === 'claude') {
+        const usage = event.usage;
+        return {
+            tokens_in: usage?.input_tokens,
+            tokens_out: usage?.output_tokens,
+            tokens_cache_read: usage?.cache_read_input_tokens,
+            tokens_cache_create: usage?.cache_creation_input_tokens,
+            total_cost_usd: event.total_cost_usd,
+            num_turns: event.num_turns,
+            model: event.model,
+            duration_ms: event.duration_ms,
+            duration_api_ms: event.api_duration_ms,
+            session_id: event.session_id,
+        };
+    }
+    // Codex path: callers may pass either a `turn.completed` event (with a
+    // nested `usage` block) or a synthesised result-like object with
+    // pre-flattened fields. Read whichever shape is present.
+    const usage = event.usage;
+    // Codex folds reasoning_output_tokens into the billed output token count
+    // (OpenAI bills reasoning tokens at output-token rates), so we collapse
+    // them here to keep cost estimation consistent with the adapter.
+    const outputTokens = usage
+        ? (usage.output_tokens ?? 0) + (usage.reasoning_output_tokens ?? 0)
+        : undefined;
+    return {
+        tokens_in: usage?.input_tokens,
+        tokens_out: outputTokens,
+        tokens_cache_read: usage?.cached_input_tokens,
+        total_cost_usd: typeof event.total_cost_usd === 'number' ? event.total_cost_usd : undefined,
+        num_turns: typeof event.num_turns === 'number' ? event.num_turns : undefined,
+        model: typeof event.model === 'string' ? event.model : undefined,
+        duration_ms: typeof event.duration_ms === 'number' ? event.duration_ms : undefined,
+    };
+}