@khorsheed/dsh-local-agent-codex 0.2.0-rc.3 → 0.2.1

package/lib/types/live-driver.js

@@ -27,7 +27,7 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { SessionId } from '@deepseek-ai/dsh-session';
 import { settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
 import { delegationEnv, persistChildSession, LiveStreamPublisher, LiveFlush, LIVE_FLUSH_INTERVAL_MS } from '@khorsheed/dsh-local-agent';
-import { appendCodexTranscriptLine, codexAssistantEvent, codexLineText, DEFAULT_DISPOSE_GRACE_MS, registerCodexMemberRun, textTask, } from './codex-cli-provider.js';
+import { appendCodexRequestHeader, appendCodexTranscriptLine, codexAssistantEvent, codexLineText, DEFAULT_DISPOSE_GRACE_MS, registerCodexMemberRun, textTask, } from './codex-cli-provider.js';
 import { codexRolloutRoundFacts } from './records.js';
 import { endpointAuthEnv, endpointConfigOverrides } from './endpoint-auth.js';
 /** Default idle lifetime of an unused resident runtime before reclaim. */
@@ -46,11 +46,6 @@ const RECLAIM_EOF_GRACE_MS = 1_000;
 export const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = LIVE_FLUSH_INTERVAL_MS;
 /** Default minimum text growth between one streaming item's snapshot messages. */
 export const DEFAULT_SNAPSHOT_MIN_CHARS = 0;
-/**
- * The app-server channel could not come up (spawn failure or handshake
- * timeout/mismatch). The provider catches exactly this and falls back to the
- * exec one-shot; any other error is a real round failure.
- */
 export class LiveChannelUnavailableError extends Error {
     constructor(message) {
         super(message);
@@ -139,16 +134,27 @@ export function codexAppServerItemToLine(item) {
             };
         }
         case 'dynamicToolCall': {
-            // Non-shell tools (e.g. the multi-agent `wait`): {id, tool, arguments, status}.
+            // Non-shell tools (e.g. the multi-agent `wait`, the deferred `exec`
+            // discovery tool): {id, tool, arguments, status, contentItems, success}
+            // — the app-server carries the result INLINE on the completed item.
             const tool = typeof item['tool'] === 'string' ? item.tool : 'dynamic';
             const args = item['arguments'] === undefined || item['arguments'] === null
                 ? undefined
                 : typeof item['arguments'] === 'string' ? item['arguments'] : JSON.stringify(item['arguments']);
+            const content = item['contentItems'];
+            const result = Array.isArray(content)
+                ? content
+                    .filter((block) => typeof block === 'object' && block !== null)
+                    .map(block => typeof block['text'] === 'string' ? block['text'] : undefined)
+                    .filter((text) => text !== undefined && text !== '')
+                    .join('\n')
+                : undefined;
             return {
                 kind: 'tool',
                 id: itemId ?? `codex-live-${randomUUID()}`,
                 name: tool,
                 ...args === undefined || args === '' ? {} : { args },
+                ...result === undefined || result === '' ? {} : { result },
             };
         }
         case 'collabAgentToolCall': {
@@ -176,15 +182,22 @@ export function codexAppServerItemToLine(item) {
 function usageFromAppServer(breakdown) {
     const input = Number(breakdown['inputTokens']);
     const cached = Number(breakdown['cachedInputTokens']);
+    const cacheWrite = Number(breakdown['cacheWriteInputTokens']);
     const output = Number(breakdown['outputTokens']);
+    // Codex's input total already contains both cache buckets (total = input +
+    // output); the shared contract keeps the three input buckets disjoint.
     const usage = {
         inputTokens: Number.isFinite(input) && Number.isFinite(cached)
-            ? Math.max(0, input - cached)
+            ? Math.max(0, input - cached - (Number.isFinite(cacheWrite) ? cacheWrite : 0))
             : Number.isFinite(input) ? input : 0,
         outputTokens: Number.isFinite(output) ? output : 0,
     };
-    if (Number.isFinite(cached) && cached > 0)
+    // The field rides every payload (zero included): write it whenever present,
+    // so "no hits" never reads as "not reported".
+    if (Number.isFinite(cached))
         usage.cacheReadTokens = cached;
+    if (Number.isFinite(cacheWrite) && cacheWrite > 0)
+        usage.cacheWriteTokens = cacheWrite;
     return usage;
 }
 /**
@@ -782,27 +795,31 @@ export class CodexLiveDriver {
         const lines = [];
         let mirrored = 0;
         let usage;
-        /** Whether a folded line already carries the round's usage (no backfill event exists). */
-        let usageCarried = false;
+        /** The cumulative turn total the wire's `tokenUsage.total` names, for the settled report. */
+        let totalUsage;
         /**
-         * The step ledger: `reservedSteps` holds every step a stream reservation
-         * consumed (in increasing order — permanently, whether the stream later
-         * completes or stays an orphan snapshot), and a sequential line folds at
-         * its index shifted past every reservation before it. A tool completed
-         * mid-stream therefore folds ABOVE the stream's step and the projection
-         * renders the round's chronological order.
+         * Per-call usage by transcript line: each `thread/tokenUsage/updated`
+         * notification closes one API call (its items have all completed), and
+         * the call's LAST line carries its `tokenUsage.last`. The map is
+         * authoritative per line, independent of the flush's withUsage flag.
          */
-        const reservedSteps = [];
+        const usageByLine = new Map();
+        /** Whether a folded line already carries usage (per-call, or the round's fallback — no backfill event exists). */
+        let usageCarried = false;
         /**
-         * The streaming items seen this round by item id:
-         * deltas accumulate into throttled snapshot assistant/messages appended
-         * at the item's reserved (turn, step) — the host folds repeated settles
-         * at one coordinate into one live-updating chat node, which is the only
-         * streaming channel left after 0.1.5 retired the durable per-chunk event.
-         * The item's completion folds at the same step and finalizes it; an entry
-         * whose completion never arrives is force-finalized at settle.
+         * The streaming items seen this round by item id: deltas accumulate into
+         * throttled snapshots at the item's step once it may open in the log
+         * (previewed live before that) — the host folds repeated settles at one
+         * coordinate into one live-updating chat node. The item's completion
+         * folds at the same step and finalizes it; an entry whose completion
+         * never arrives is force-finalized at settle. A tool that completes
+         * mid-stream folds after the stream, keeping the round's chronology.
          */
         const streams = new Map();
+        /** Provisional stream keys (live flush and preview identity), never log steps. */
+        let streamKeys = 0;
+        /** Line indexes already written (a line may fold ahead of an earlier one it chronologically precedes). */
+        const folded = new Set();
         /** The item deltas currently accumulate into (items stream sequentially). */
         let activeStream;
         /** Items/completions that arrived before the turn id was known. */
@@ -850,6 +867,29 @@ export class CodexLiveDriver {
         const streamPublisher = localAgent?.liveStreams === undefined ? undefined
             : new LiveStreamPublisher(localAgent.liveStreams, childSession, turn, persist, error => this.ctx.logger.warn(`live checkpoint failed: ${String(error)}`));
         const liveFlush = new LiveFlush(error => this.ctx.logger.warn(`live mirror flush failed: ${String(error)}`), this.config.snapshotMinIntervalMs ?? DEFAULT_SNAPSHOT_MIN_INTERVAL_MS);
+        // The step ledger. The log admits steps strictly in sequence — one open
+        // at a time, numbered when it is WRITTEN (`lastStep`) — while the round's
+        // chronology is kept by start order: a stream sorts before every line
+        // that completed after its first delta (`after` = lines completed before
+        // it began). A stream's step opens in the log only once it is the oldest
+        // unfinished stream and everything before it is written; until then the
+        // browser previews it (`preview`), and its fold writes the text anyway.
+        let lastStep = 0;
+        let openStep;
+        const openStreamStep = (stream) => {
+            lastStep += 1;
+            childSession.append('step/start', { turn, step: lastStep });
+            stream.durable = lastStep;
+            stream.opened = true;
+            openStep = lastStep;
+        };
+        const closeOpenStep = () => {
+            if (openStep === undefined)
+                return;
+            childSession.append('step/end', { turn, step: openStep });
+            openStep = undefined;
+        };
+        const canOpenStream = (stream) => openStep === undefined && mirrored >= stream.after && streams.keys().next().value === stream.itemId;
         const pendingStreamArrival = new Map();
         const appendStreamSnapshot = (stream, force, interrupted, withUsage = false, final = false) => {
             if (stream.text.trim() === '')
@@ -864,31 +904,39 @@ export class CodexLiveDriver {
             liveFlush.cancel(stream.step);
             const receivedAt = pendingStreamArrival.get(stream.step) ?? now;
             pendingStreamArrival.delete(stream.step);
-            if (streamPublisher !== undefined && !final) {
-                if (!stream.opened) {
-                    childSession.append('step/start', { turn, step: stream.step });
-                    stream.opened = true;
+            if (!stream.opened) {
+                if (canOpenStream(stream))
+                    openStreamStep(stream);
+                else if (!final) {
+                    // Not its turn in the log yet: show it live, write it later.
+                    streamPublisher?.preview(stream.step, stream.kind, stream.text, { itemId: stream.itemId, receivedAt });
+                    return;
                 }
-                streamPublisher.update(stream.step, stream.kind, stream.text, { receivedAt });
+                else {
+                    // Settle: every line has folded; take the next step.
+                    closeOpenStep();
+                    openStreamStep(stream);
+                }
+            }
+            if (streamPublisher !== undefined && !final) {
+                streamPublisher.update(stream.durable, stream.kind, stream.text, { receivedAt });
                 stream.lastSnapshotAt = now;
                 stream.lastSnapshotLen = stream.text.length;
                 return;
             }
-            if (!stream.opened) {
-                childSession.append('step/start', { turn, step: stream.step });
-                stream.opened = true;
-            }
-            const attachUsage = withUsage && !usageCarried && usage !== undefined;
+            // Per-call folds carry the accounting; a final snapshot only falls back
+            // to the last-call read when the wire named no per-call usage at all.
+            const attachUsage = withUsage && !usageCarried && usageByLine.size === 0 && usage !== undefined;
             childSession.append('assistant/message', {
                 turn,
-                step: stream.step,
+                step: stream.durable,
                 message: codexAssistantEvent([
                     stream.kind === 'think'
                         ? { type: 'reasoning', text: stream.text }
                         : { type: 'text', text: stream.text },
                 ]),
                 stream: [],
-                ...withUsage && !usageCarried && usage !== undefined ? { usage } : {},
+                ...withUsage && !usageCarried && usageByLine.size === 0 && usage !== undefined ? { usage } : {},
                 ...interrupted ? { interrupted: true } : {},
             }, { surfaceOp: 'append' });
             if (attachUsage)
@@ -897,11 +945,21 @@ export class CodexLiveDriver {
             stream.lastSnapshotLen = stream.text.length;
             persist();
         };
+        /** Close a stream's live presentation once its final text is in the log. */
+        const finishStream = (stream) => {
+            liveFlush.cancel(stream.step);
+            streams.delete(stream.itemId);
+            if (activeStream === stream.itemId)
+                activeStream = undefined;
+            streamPublisher?.finish(stream.step);
+            if (stream.durable !== undefined)
+                streamPublisher?.finish(stream.durable);
+        };
         /**
-         * Reserve the step one new streaming item will occupy — past every
-         * completed line (folded or held back) and every earlier reservation. A
-         * different item's deltas force one final snapshot of the current stream
-         * (its completion still folds at its own reserved step when it lands).
+         * Track one new streaming item: its provisional key (live flush and
+         * preview identity) and how many lines had completed when it began. A
+         * different item's deltas force one freshness snapshot of the current
+         * stream.
          */
         const reserveStream = (itemId, kind) => {
             if (activeStream !== undefined && activeStream !== itemId) {
@@ -915,75 +973,96 @@ export class CodexLiveDriver {
             }
             let stream = streams.get(itemId);
             if (stream === undefined) {
-                const step = lines.length + reservedSteps.length + 1;
-                reservedSteps.push(step);
-                stream = { itemId, kind, step, text: '', lastSnapshotAt: 0, lastSnapshotLen: 0, opened: false };
+                streamKeys += 1;
+                stream = { itemId, kind, step: streamKeys, after: lines.length, text: '', lastSnapshotAt: 0, lastSnapshotLen: 0, opened: false };
                 streams.set(itemId, stream);
             }
             activeStream = itemId;
         };
-        /** The sequential fold step for `lines[index]`: its position shifted past every reservation before it. */
-        const foldStep = (index) => {
-            let step = index + 1;
-            for (const reserved of reservedSteps) {
-                if (reserved <= step)
-                    step += 1;
-                else
-                    break;
+        /** The stream a completed line finalizes, if it was streamed. */
+        const streamOfLine = (line) => line === undefined || line.kind === 'tool' ? undefined : streams.get(line.itemId ?? '');
+        /** Write lines[index] at the next step(s). */
+        const foldLine = (index, lineUsage) => {
+            const line = lines[index];
+            const stream = streamOfLine(line);
+            if (stream !== undefined) {
+                // A streamed item finalizes its own step (opening it now if no
+                // snapshot ever could) and closes it.
+                if (!stream.opened) {
+                    closeOpenStep();
+                    openStreamStep(stream);
+                }
+                const blocks = stream.kind === 'think'
+                    ? [{ type: 'reasoning', text: line.kind === 'tool' ? '' : line.text }]
+                    : [{ type: 'text', text: line.kind === 'tool' ? '' : line.text }];
+                childSession.append('assistant/message', {
+                    turn,
+                    step: stream.durable,
+                    message: codexAssistantEvent(blocks),
+                    stream: [],
+                    ...lineUsage === undefined ? {} : { usage: lineUsage },
+                }, { surfaceOp: 'append' });
+                finishStream(stream);
+                closeOpenStep();
+            }
+            else {
+                closeOpenStep();
+                lastStep += 1;
+                appendCodexTranscriptLine(childSession, turn, lastStep, line, lineUsage);
             }
-            return step;
+            folded.add(index);
+            localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: codexLineText(line) });
         };
-        /** Mirror folded lines [mirrored, upto); the last line is held back until completion. */
+        /**
+         * Mirror the completed lines before `upto` in chronological order; the
+         * last line is held back until completion. A line waits behind every
+         * stream that began before it completed: that stream's line folds first,
+         * or — while it is still streaming — the mirror stops until it lands.
+         */
         const mirrorUpTo = (upto, withUsage) => {
-            // The usage rides the last NON-tool line (tool events carry no usage
-            // slot, and a kill mid-command ends the transcript with a tool line).
-            // A carrier mirrored in an earlier flush (before the usage was knowable)
-            // loses the accounting — host 0.1.5 has no usage-backfill event.
+            // Per-call usage rides the line its notification stamped, whenever that
+            // line folds. The fallback (a wire that never named per-call usage)
+            // rides the last NON-tool line once — tool/call and tool/result events
+            // carry no usage slot, and a kill mid-command ends the transcript with
+            // a tool line. A carrier mirrored in an earlier flush (before the usage
+            // was knowable) loses the accounting — host 0.1.5 has no usage-backfill
+            // event.
             let usageIndex = -1;
-            if (withUsage) {
+            if (withUsage && usageByLine.size === 0) {
                 for (let index = 0; index < lines.length; index += 1) {
                     if (lines[index]?.kind !== 'tool')
                         usageIndex = index;
                 }
             }
-            for (let index = mirrored; index < upto; index += 1) {
-                const line = lines[index];
-                if (line === undefined)
-                    continue;
+            const usageFor = (index) => {
+                const own = usageByLine.get(index);
+                if (own !== undefined) {
+                    usageCarried = true;
+                    return own;
+                }
                 const lineUsage = withUsage && index === usageIndex ? usage : undefined;
                 if (lineUsage !== undefined)
                     usageCarried = true;
-                const itemId = line.kind === 'tool' ? undefined : line.itemId;
-                const stream = itemId === undefined ? undefined : streams.get(itemId);
-                if (itemId !== undefined && stream !== undefined) {
-                    // A streamed item folds at its reserved step, finalizing the
-                    // snapshots: the step opens only if no snapshot ever landed (a
-                    // fast item that stayed under the throttle), and closes here.
-                    liveFlush.cancel(stream.step);
-                    streams.delete(itemId);
-                    if (activeStream === itemId)
-                        activeStream = undefined;
-                    if (!stream.opened)
-                        childSession.append('step/start', { turn, step: stream.step });
-                    const blocks = stream.kind === 'think'
-                        ? [{ type: 'reasoning', text: line.kind === 'tool' ? '' : line.text }]
-                        : [{ type: 'text', text: line.kind === 'tool' ? '' : line.text }];
-                    childSession.append('assistant/message', {
-                        turn,
-                        step: stream.step,
-                        message: codexAssistantEvent(blocks),
-                        stream: [],
-                        ...lineUsage === undefined ? {} : { usage: lineUsage },
-                    }, { surfaceOp: 'append' });
-                    streamPublisher?.finish(stream.step);
-                    childSession.append('step/end', { turn, step: stream.step });
-                }
-                else {
-                    appendCodexTranscriptLine(childSession, turn, foldStep(index), line, lineUsage);
+                return lineUsage;
+            };
+            outer: for (let index = mirrored; index < upto; index += 1) {
+                if (folded.has(index))
+                    continue;
+                const own = streamOfLine(lines[index]);
+                // Streams order among themselves by start; a plain line follows every
+                // stream that began before it completed.
+                const all = [...streams.values()];
+                const before = own === undefined ? all.filter(stream => stream.after <= index) : all.slice(0, all.indexOf(own));
+                for (const earlier of before) {
+                    const at = lines.findIndex((line, position) => position > index && position < upto && !folded.has(position) && streamOfLine(line) === earlier);
+                    if (at < 0)
+                        break outer;
+                    foldLine(at, usageFor(at));
                 }
-                mirrored = index + 1;
-                localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: codexLineText(line) });
+                foldLine(index, usageFor(index));
             }
+            while (folded.has(mirrored))
+                mirrored += 1;
             if (upto > 0)
                 persist();
         };
@@ -993,6 +1072,17 @@ export class CodexLiveDriver {
             // The boundary opens after the accept ack (a definitive reject leaves no
             // dangling turn/start); the prompt and any early items flush inside it.
             childSession.append('turn/start', { turn });
+            // The provider's own launch facts are the child log's request config —
+            // codex's notifications never carry model/effort, so the turn/start
+            // request parameters the provider sends are the authoritative source.
+            // The header contract requires a model: without one nothing is recorded.
+            if (spec.configuration?.model !== undefined) {
+                appendCodexRequestHeader(childSession, {
+                    provider: 'codex-local',
+                    model: spec.configuration.model,
+                    ...spec.configuration.effort === undefined ? {} : { reasoningEffort: spec.configuration.effort },
+                });
+            }
             childSession.append('user/message', createUserMessage({
                 content: [{ type: 'text', text: task }],
                 source: { kind: 'user' },
@@ -1020,8 +1110,9 @@ export class CodexLiveDriver {
                 if (line === undefined)
                     return;
                 lines.push(line);
-                // Hold back the volatile last line until turn/completed (it is the
-                // round's usage carrier) — the exec live mirror's exact rule.
+                // Hold back the volatile last line (a tool result may still merge
+                // into it) — per-call usage arrives on thread/tokenUsage/updated and
+                // folds with the line whenever it lands.
                 mirrorUpTo(lines.length - 1, false);
                 return;
             }
@@ -1050,19 +1141,41 @@ export class CodexLiveDriver {
             if (method === 'thread/tokenUsage/updated') {
                 const tokenUsage = params['tokenUsage'];
                 const last = tokenUsage?.['last'];
-                if (last !== undefined)
+                const total = tokenUsage?.['total'];
+                // A total with no numbers is "not reported" (never override the
+                // per-call read with an empty object).
+                if (total !== undefined && (Number.isFinite(Number(total['inputTokens'])) || Number.isFinite(Number(total['outputTokens'])))) {
+                    totalUsage = usageFromAppServer(total);
+                }
+                if (last !== undefined) {
                     usage = usageFromAppServer(last);
+                    // One notification closes one API call (the rollout's token_count
+                    // position: right after the call's last item). Stamp the call's own
+                    // usage on its last line and flush the completed prefix with it;
+                    // the volatile last line keeps its hold (a tool result may still
+                    // merge into it) and folds with its mapped usage whenever it lands.
+                    if (lines.length > 0) {
+                        usageByLine.set(lines.length - 1, usage);
+                        mirrorUpTo(lines.length - 1, true);
+                    }
+                }
                 return;
             }
             if (method === 'turn/completed') {
                 const turnData = params['turn'];
-                mirrorUpTo(lines.length, true);
-                resolveCompletion({
-                    status: String(turnData['status']),
-                    ...(turnData['error'] === null || turnData['error'] === undefined
-                        ? {}
-                        : { error: turnData['error'] }),
-                });
+                // A fold failure must never skip the completion: the round settles
+                // with its mirrored prefix instead of hanging forever.
+                try {
+                    mirrorUpTo(lines.length, true);
+                }
+                finally {
+                    resolveCompletion({
+                        status: String(turnData['status']),
+                        ...(turnData['error'] === null || turnData['error'] === undefined
+                            ? {}
+                            : { error: turnData['error'] }),
+                    });
+                }
             }
         };
         /** Route one wire notification: round-scoped, turn-id tagged, early ones buffered. */
@@ -1184,6 +1297,15 @@ export class CodexLiveDriver {
                 // flush it now (the exec settle-mirror's partial-work contract).
                 if (mirrored < lines.length)
                     mirrorUpTo(lines.length, true);
+                // A line still waiting behind a stream whose completion never came:
+                // finalize that stream from its last snapshot, then keep folding.
+                while (mirrored < lines.length && streams.size > 0) {
+                    const oldest = streams.values().next().value;
+                    appendStreamSnapshot(oldest, true, settled.stopReason !== 'completed', false, true);
+                    finishStream(oldest);
+                    closeOpenStep();
+                    mirrorUpTo(lines.length, true);
+                }
                 // Streams whose item/completed never arrived (abort, or the server
                 // ended the turn mid-item) still finalize INSIDE the turn window:
                 // one forced snapshot each — interrupted on a non-completed round,
@@ -1193,9 +1315,8 @@ export class CodexLiveDriver {
                     const remaining = [...streams.values()];
                     for (const [position, stream] of remaining.entries()) {
                         appendStreamSnapshot(stream, true, settled.stopReason !== 'completed', position === remaining.length - 1, true);
-                        streamPublisher?.finish(stream.step);
-                        if (stream.opened)
-                            childSession.append('step/end', { turn, step: stream.step });
+                        finishStream(stream);
+                        closeOpenStep();
                     }
                     streams.clear();
                     activeStream = undefined;
@@ -1248,7 +1369,11 @@ export class CodexLiveDriver {
                         windowStart: startedAtMs,
                         cwd: spec.cwd,
                     });
-                    const settledUsage = usage ?? facts.usage;
+                    // The settled report wants the round TOTAL: prefer the wire's
+                    // cumulative tokenUsage.total (the per-call `last` under-reports a
+                    // multi-call round); the rollout read is the non-completed turn's
+                    // fallback, as before.
+                    const settledUsage = totalUsage ?? usage ?? facts.usage;
                     const round = {
                         ...facts.model === undefined ? {} : { observedModel: facts.model },
                         ...facts.cliVersion === undefined ? {} : { cliVersion: facts.cliVersion },

package/lib/types/model-broker.js

@@ -39,6 +39,42 @@ function dedupeChoices(layers) {
     }
     return choices;
 }
+/**
+ * Scope the served directory to the surface asking for it (the same helper
+ * lives in each provider's broker — fold into the family core when the
+ * directory faces next evolve):
+ *
+ * - memberless (the card's add-model dialog, the invite picker): the
+ *   endpoint's served catalog only — the configuration/history extras the
+ *   broker's info extension adds for STATUS display must never become add
+ *   candidates;
+ * - a member whose harness has a curated list: the list IS the vocabulary,
+ *   in the list's own order (the same rule `choices` already follows) — a
+ *   curated value the endpoint no longer serves stays as a bare row (the
+ *   card shows it the same way), and the member's current effective model is
+ *   kept visible as a bare entry when it sits outside the list, so a pre-list
+ *   binding never renders blank;
+ * - a member without a curated list: the legacy extended vocabulary.
+ */
+function scopeServedDirectory(directory, opts) {
+    if (opts.member && opts.curated.length === 0)
+        return directory;
+    const served = directory.entries.filter(entry => entry.source === 'native');
+    if (!opts.member)
+        return { ...directory, entries: served };
+    const byValue = new Map(served.flatMap(entry => entry.resolvedModel === undefined
+        ? [[entry.value, entry]]
+        : [[entry.value, entry], [entry.resolvedModel, entry]]));
+    // Curated ORDER leads (the card's first row is the default); a curated value
+    // the endpoint no longer serves stays listed as a bare row, exactly like the
+    // card shows it.
+    const entries = opts.curated.map(value => byValue.get(value) ?? { value, label: value, source: 'configuration' });
+    const current = opts.current?.trim();
+    if (current !== undefined && current !== '' && !entries.some(entry => entry.value === current || entry.resolvedModel === current)) {
+        entries.push({ value: current, label: current, source: 'configuration' });
+    }
+    return { ...directory, entries };
+}
 export class CodexModelBroker {
     deps;
     constructor(deps) {
@@ -88,7 +124,12 @@ export class CodexModelBroker {
         if (refresh)
             await this.deps.refreshDirectory?.(home, this.deps.cwd?.(childSessionId));
         const info = await this.modelInfo(childSessionId, childSessionId === undefined ? undefined : this.deps.ctx.localAgent.getDelegation(childSessionId)?.model);
-        return info.directory ?? { entries: [], complete: false, customInput: true, status: 'unsupported', refreshing: false, revision: 0 };
+        const directory = info.directory ?? { entries: [], complete: false, customInput: true, status: 'unsupported', refreshing: false, revision: 0 };
+        return scopeServedDirectory(directory, {
+            member: childSessionId !== undefined,
+            curated: this.deps.modelList?.(home) ?? [],
+            current: info.effective,
+        });
     }
     async *followModelDirectory(childSessionId, signal) {
         if (this.deps.followDirectory === undefined) {

package/lib/types/records.d.ts

@@ -35,10 +35,12 @@ export declare function listCodexSessions(homeDir: string): Promise<readonly Loc
  * `input_tokens` is the TOTAL input including cache hits (OpenAI-style
  * accounting, confirmed against `total_tokens` in the rollout token_count),
  * and `cached_input_tokens` is the cache-read subset — so the uncached
- * bucket subtracts the cached portion to avoid double counting. There is no
- * cache-write concept, so that bucket is omitted (the shared four-bucket
- * contract: uncached input, output, cache read, cache write — codex fills
- * the first three).
+ * bucket subtracts the cached portion to avoid double counting.
+ * `cached_input_tokens` rides every payload (zero included), so
+ * `cacheReadTokens` is written whenever the field is present — a reader can
+ * tell "no hits" from "not reported". Codex also reports cache creation
+ * (`cache_write_input_tokens`), mapped to `cacheWriteTokens` (the shared
+ * four-bucket contract: uncached input, output, cache read, cache write).
  * @param usage - the raw codex usage object (`turn.completed`'s `usage` or a
  *   rollout `token_count` `info.last_token_usage`/`total_token_usage`).
  * @returns the shared usage record.

package/lib/types/records.js

@@ -149,10 +149,12 @@ export async function listCodexSessions(homeDir) {
  * `input_tokens` is the TOTAL input including cache hits (OpenAI-style
  * accounting, confirmed against `total_tokens` in the rollout token_count),
  * and `cached_input_tokens` is the cache-read subset — so the uncached
- * bucket subtracts the cached portion to avoid double counting. There is no
- * cache-write concept, so that bucket is omitted (the shared four-bucket
- * contract: uncached input, output, cache read, cache write — codex fills
- * the first three).
+ * bucket subtracts the cached portion to avoid double counting.
+ * `cached_input_tokens` rides every payload (zero included), so
+ * `cacheReadTokens` is written whenever the field is present — a reader can
+ * tell "no hits" from "not reported". Codex also reports cache creation
+ * (`cache_write_input_tokens`), mapped to `cacheWriteTokens` (the shared
+ * four-bucket contract: uncached input, output, cache read, cache write).
  * @param usage - the raw codex usage object (`turn.completed`'s `usage` or a
  *   rollout `token_count` `info.last_token_usage`/`total_token_usage`).
  * @returns the shared usage record.
@@ -161,9 +163,12 @@ export function usageFromCodex(usage) {
     const raw = usage;
     const input = Number(raw.input_tokens);
     const cached = Number(raw.cached_input_tokens);
+    const cacheWrite = Number(raw.cache_write_input_tokens);
     const output = Number(raw.output_tokens);
+    // `input_tokens` already contains both cache buckets (total = input +
+    // output); the shared contract keeps the three input buckets disjoint.
     const uncached = Number.isFinite(input) && Number.isFinite(cached)
-        ? Math.max(0, input - cached)
+        ? Math.max(0, input - cached - (Number.isFinite(cacheWrite) ? cacheWrite : 0))
         : Number.isFinite(input)
             ? input
             : 0;
@@ -171,8 +176,10 @@ export function usageFromCodex(usage) {
         inputTokens: uncached,
         outputTokens: Number.isFinite(output) ? output : 0,
     };
-    if (Number.isFinite(cached) && cached > 0)
+    if (Number.isFinite(cached))
         usageRecord.cacheReadTokens = cached;
+    if (Number.isFinite(cacheWrite) && cacheWrite > 0)
+        usageRecord.cacheWriteTokens = cacheWrite;
     return usageRecord;
 }
 /**

package/package.json

@@ -8,7 +8,7 @@
     "local-agent",
     "codex"
   ],
-  "version": "0.2.0-rc.3",
+  "version": "0.2.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -69,7 +69,7 @@
     "dsh": ">=0.1.5-rc.1 <0.3.0-0"
   },
   "dependencies": {
-    "@khorsheed/dsh-local-agent": "^0.2.0-rc.3"
+    "@khorsheed/dsh-local-agent": "^0.2.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",