@deepseek-harness-tui/dsh-tui 0.12.0 → 0.14.0

package/lib/types/backends/codex/session/controls.d.ts

@@ -0,0 +1,37 @@
+/** Thin wrappers over Codex's control requests; choices persist only in TUI prefs. */
+import type { AccountView, ModelOption, SessionCapabilities } from '../../../agent/capabilities.js';
+import type { AgentEvent } from '../../../agent/events.js';
+import { type Rec } from '../narrow.js';
+import type { CodexPrefs } from '../prefs.js';
+import type { CodexHub } from '../rpc/hub.js';
+import type { ItemContext } from '../translate/items.js';
+import type { SettingsSnapshot } from '../translate/live.js';
+interface ControlsDeps {
+    readonly hub: CodexHub;
+    readonly prefs: CodexPrefs;
+    readonly ctx: ItemContext;
+    readonly settings: SettingsSnapshot;
+    readonly cwd: string;
+    threadId(): string;
+    busy(): boolean;
+    emit(events: readonly AgentEvent[]): void;
+    submitText(text: string): Promise<void>;
+    account?(): Promise<AccountView>;
+    mappedModels?(): readonly ModelOption[];
+    actualModel?(id: string): string;
+    debug(message: string): void;
+}
+/** Policy objects used by turn/start and thread/settings/update. */
+export declare function sandboxPolicy(mode: string, cwd: string): Rec;
+export declare function createCodexControls(deps: ControlsDeps): {
+    capabilities: Pick<SessionCapabilities, "context" | "effort" | "compact" | "rename" | "init" | "mcp" | "models" | "modes" | "account">;
+    initialize(): Promise<void>;
+    /** Knobs not yet applied by a turn (or an idle settings update). */
+    turnOverrides(): Rec;
+    /** A refused turn did not apply its settings. Drop only unsupported Plan. */
+    turnFailed(error: unknown, overrides: Rec): void;
+    note(method: string, params: Rec): boolean;
+    readonly planSupported: boolean;
+};
+export {};
+//# sourceMappingURL=controls.d.ts.map

package/lib/types/backends/codex/session/controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controls.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/session/controls.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,KAAK,EAAE,WAAW,EAA+B,WAAW,EAAc,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAC5I,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAG1D,OAAO,EAAiC,KAAK,GAAG,EAAE,MAAM,cAAc,CAAA;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAG7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG5D,UAAU,YAAY;IACpB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,IAAI,MAAM,CAAA;IAClB,IAAI,IAAI,OAAO,CAAA;IACf,IAAI,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAAA;IACzC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,OAAO,CAAC,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IAChC,YAAY,CAAC,IAAI,SAAS,WAAW,EAAE,CAAA;IACvC,WAAW,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IAChC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAID,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,GAAG,CAM5D;AAWD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY;;kBAoM9B,OAAO,CAAC,IAAI,CAAC;IASjC,oEAAoE;qBACnD,GAAG;IACpB,6EAA6E;sBAC3D,OAAO,aAAa,GAAG,GAAG,IAAI;iBAYnC,MAAM,UAAU,GAAG,GAAG,OAAO;;EAoB7C"}

package/lib/types/backends/codex/session/controls.js

@@ -0,0 +1,303 @@
+import { t } from '../../../i18n.js';
+import { CODEX_MODE_PARAMS, isCodexModeId } from '../modes.js';
+import { arr, errorText, num, rec, str } from '../narrow.js';
+import { CLIENT, NOTIFY } from '../protocol/index.js';
+import { rpcCode, RPC_ERROR } from '../rpc/client.js';
+import { CODEX_INIT_PROMPT } from './prompts.js';
+const catalogs = new WeakMap();
+/** Policy objects used by turn/start and thread/settings/update. */
+export function sandboxPolicy(mode, cwd) {
+    switch (mode) {
+        case 'read-only': return { type: 'readOnly', networkAccess: false };
+        case 'danger-full-access': return { type: 'dangerFullAccess' };
+        default: return { type: 'workspaceWrite', writableRoots: [cwd], networkAccess: false, excludeTmpdirEnvVar: false, excludeSlashTmp: false };
+    }
+}
+function permissionOptions() {
+    return [
+        { id: 'read-only', label: t('codex-mode-read-only'), description: t('codex-mode-read-only-desc') },
+        { id: 'auto', label: t('codex-mode-auto'), description: t('codex-mode-auto-desc') },
+        { id: 'full-access', label: t('codex-mode-full-access'), description: t('codex-mode-full-access-desc') },
+    ];
+}
+const planOption = () => ({ id: 'plan', label: t('codex-mode-plan'), description: t('codex-mode-plan-desc') });
+export function createCodexControls(deps) {
+    const { hub, settings, ctx, prefs } = deps;
+    let rows = [];
+    let planSupported = true;
+    let settingsSupported = true;
+    let pending = {};
+    let appliedCollaboration = settings.collaborationMode;
+    let context = { used: 0, max: undefined };
+    let requestedTitle;
+    let catalog = catalogs.get(hub);
+    if (catalog === undefined) {
+        catalog = {};
+        catalogs.set(hub, catalog);
+    }
+    const models = async () => {
+        catalog.rows ??= (async () => {
+            const collected = [];
+            let cursor;
+            do {
+                const answer = rec(await hub.call(CLIENT.modelList, { includeHidden: false, limit: 100, ...(cursor === undefined ? {} : { cursor }) }));
+                collected.push(...arr(answer?.data).flatMap(raw => rec(raw) === undefined ? [] : [rec(raw)]));
+                cursor = str(answer?.nextCursor) ?? undefined;
+            } while (cursor !== undefined && cursor !== '');
+            return collected;
+        })().catch(error => { catalog.rows = undefined; throw error; });
+        rows = await catalog.rows;
+        const options = rows.filter(row => row.hidden !== true).flatMap(row => {
+            const id = str(row.model) ?? str(row.id);
+            return id === undefined ? [] : [{ id, label: str(row.displayName) ?? id, ...(str(row.description) === undefined ? {} : { description: str(row.description) }) }];
+        });
+        for (const mapped of deps.mappedModels?.() ?? [])
+            if (!options.some(option => option.id === mapped.id))
+                options.push(mapped);
+        return options;
+    };
+    const currentRow = () => rows.find(row => row.model === settings.model || row.id === settings.model);
+    const collaboration = (mode, model = settings.model, effort = settings.effort) => ({ mode, settings: { model, reasoning_effort: effort, developer_instructions: null } });
+    /** An accepted update is sticky server-side, not an override for every turn. */
+    const acknowledge = (applied) => {
+        appliedCollaboration = rec(applied.collaborationMode) ?? appliedCollaboration;
+        for (const [key, value] of Object.entries(applied)) {
+            if (JSON.stringify(pending[key]) === JSON.stringify(value))
+                delete pending[key];
+        }
+    };
+    let sentOverrides;
+    const update = async (change) => {
+        // A deferred mode has higher wire precedence than model/effort. Keep its
+        // embedded settings in sync without touching its developer instructions.
+        const mode = rec(pending.collaborationMode);
+        if (mode !== undefined && change.collaborationMode === undefined && (change.model !== undefined || change.effort !== undefined)) {
+            change = { ...change, collaborationMode: { ...mode, settings: { ...rec(mode.settings),
+                        ...(change.model === undefined ? {} : { model: change.model }),
+                        ...(change.effort === undefined ? {} : { reasoning_effort: change.effort }),
+                    } } };
+        }
+        const before = pending;
+        pending = { ...pending, ...change };
+        if (deps.busy() || !settingsSupported)
+            return;
+        try {
+            await hub.call(CLIENT.threadSettingsUpdate, { threadId: deps.threadId(), ...change });
+            acknowledge(change);
+        }
+        catch (error) {
+            const code = rpcCode(error);
+            if ((code !== RPC_ERROR.methodNotFound && code !== RPC_ERROR.invalidParams) || (code === RPC_ERROR.invalidParams && change.collaborationMode !== undefined)) {
+                for (const [key, value] of Object.entries(change)) {
+                    if (JSON.stringify(pending[key]) !== JSON.stringify(value))
+                        continue;
+                    if (before[key] === undefined)
+                        delete pending[key];
+                    else
+                        pending[key] = before[key];
+                }
+                if (code === RPC_ERROR.invalidParams && change.collaborationMode !== undefined) {
+                    planSupported = false;
+                    delete pending.collaborationMode;
+                    throw new Error(t('codex-capability-unavailable', { feature: t('codex-mode-plan') }));
+                }
+                throw error;
+            }
+            settingsSupported = false;
+            deps.emit([{ type: 'notice', level: 'warning', key: 'codex-settings-deferred', text: t('codex-settings-deferred') }]);
+        }
+    };
+    const effortLevels = () => arr(currentRow()?.supportedReasoningEfforts).flatMap(raw => {
+        const id = str(rec(raw)?.reasoningEffort);
+        if (id === undefined)
+            return [];
+        const labels = { none: t('codex-effort-none'), minimal: t('codex-effort-minimal'), low: t('codex-effort-low'), medium: t('codex-effort-medium'), high: t('codex-effort-high'), xhigh: t('codex-effort-xhigh'), ultra: t('codex-effort-ultra') };
+        return [{ id, label: labels[id] ?? id }];
+    });
+    const capabilities = {
+        models: {
+            list: models,
+            current: () => ({ model: settings.model }),
+            display: () => deps.actualModel?.(settings.model),
+            async set(ref) {
+                await models();
+                const model = deps.actualModel?.(ref.model) ?? ref.model;
+                const nextRow = rows.find(row => row.model === model || row.id === model);
+                const available = arr(nextRow?.supportedReasoningEfforts).map(raw => str(rec(raw)?.reasoningEffort));
+                const effort = settings.effort !== null && available.length > 0 && !available.includes(settings.effort) ? str(nextRow?.defaultReasoningEffort) ?? null : settings.effort;
+                await update({ model, ...(effort === settings.effort ? {} : { effort }) });
+                const effortChanged = effort !== settings.effort;
+                settings.model = model;
+                settings.effort = effort;
+                ctx.model = model;
+                prefs.write({ model: ref.model, ...(effortChanged ? { effort } : {}) });
+                deps.emit([{ type: 'model.changed', model, source: 'user' }, { type: 'effort.changed', effort }]);
+                return { kind: 'switched' };
+            },
+        },
+        effort: {
+            levels: effortLevels,
+            current: () => settings.effort ?? undefined,
+            async set(id) {
+                if (rows.length === 0)
+                    await models();
+                if (id !== null && !effortLevels().some(option => option.id === id))
+                    throw new Error(t('effort-invalid', { id, ids: effortLevels().map(option => option.id).join(', ') }));
+                const applied = id ?? str(currentRow()?.defaultReasoningEffort) ?? null;
+                await update({ effort: applied });
+                settings.effort = applied;
+                prefs.write({ effort: id });
+                deps.emit([{ type: 'effort.changed', effort: applied }]);
+            },
+        },
+        modes: {
+            list: () => [...permissionOptions(), ...(planSupported ? [planOption()] : [])],
+            cycle: () => {
+                const base = permissionOptions().find(option => option.id === settings.permissionMode) ?? { id: settings.permissionMode ?? 'custom', label: settings.permissionMode ?? 'custom' };
+                return planSupported ? [base, planOption()] : [base];
+            },
+            current: () => settings.modeId,
+            async set(id) {
+                if (id !== 'plan' && !isCodexModeId(id) && id !== settings.permissionMode)
+                    throw new Error(t('codex-mode-invalid', { mode: id }));
+                if (id === 'plan' && !planSupported)
+                    throw new Error(t('codex-capability-unavailable', { feature: t('codex-mode-plan') }));
+                const plan = id === 'plan';
+                const switching = plan !== (settings.modeId === 'plan');
+                const change = planSupported && switching ? { collaborationMode: collaboration(plan ? 'plan' : 'default') } : {};
+                if (!plan && isCodexModeId(id)) {
+                    const params = CODEX_MODE_PARAMS[id];
+                    change.approvalPolicy = params.approvalPolicy;
+                    change.sandboxPolicy = sandboxPolicy(params.sandbox, deps.cwd);
+                }
+                await update(change);
+                if (!plan && isCodexModeId(id)) {
+                    settings.permissionMode = id;
+                    settings.approvalPolicy = change.approvalPolicy;
+                    settings.sandboxPolicy = change.sandboxPolicy;
+                    prefs.write({ mode: id });
+                }
+                settings.collaborationMode = rec(change.collaborationMode) ?? settings.collaborationMode;
+                settings.modeId = plan ? 'plan' : settings.permissionMode ?? id;
+                prefs.write({ plan });
+                deps.emit([{ type: 'mode.changed', modeId: settings.modeId }]);
+            },
+        },
+        compact: {
+            async run() {
+                if (deps.busy())
+                    throw new Error(t('codex-command-idle'));
+                ctx.compactRequested = true;
+                try {
+                    await hub.call(CLIENT.threadCompactStart, { threadId: deps.threadId() });
+                }
+                catch (error) {
+                    ctx.compactRequested = false;
+                    throw error;
+                }
+            },
+        },
+        context: { usage: async () => ({ ...context, categories: [] }) },
+        account: {
+            async info() {
+                if (deps.account !== undefined)
+                    return deps.account();
+                const response = rec(await hub.call(CLIENT.accountRead, { refreshToken: false }));
+                const account = rec(response?.account);
+                return { provider: str(account?.type) === 'apiKey' ? 'openai' : str(account?.provider) ?? 'openai', ...(str(account?.planType) === undefined ? {} : { subscription: str(account?.planType) }) };
+            },
+        },
+        mcp: {
+            async status() {
+                const servers = [];
+                let cursor;
+                do {
+                    const answer = rec(await hub.call(CLIENT.mcpServerStatusList, { threadId: deps.threadId(), detail: 'toolsAndAuthOnly', limit: 100, ...(cursor === undefined ? {} : { cursor }) }));
+                    for (const raw of arr(answer?.data)) {
+                        const server = rec(raw);
+                        const name = str(server?.name);
+                        if (name !== undefined)
+                            servers.push({ name, status: str(server?.runtimeStatus) ?? str(server?.authStatus) ?? 'unknown', toolCount: Object.keys(rec(server?.tools) ?? {}).length });
+                    }
+                    cursor = str(answer?.nextCursor);
+                } while (cursor !== undefined && cursor !== '');
+                return servers;
+            },
+            reconnect: async () => { await hub.call(CLIENT.mcpServerReload, {}); await capabilities.mcp.status(); },
+        },
+        rename: {
+            async rename(title) {
+                requestedTitle = title;
+                try {
+                    await hub.call(CLIENT.threadNameSet, { threadId: deps.threadId(), name: title });
+                }
+                catch (error) {
+                    requestedTitle = undefined;
+                    throw error;
+                }
+            },
+        },
+        init: { run: () => deps.submitText(CODEX_INIT_PROMPT) },
+    };
+    return {
+        capabilities,
+        async initialize() {
+            await Promise.all([
+                models().catch(error => deps.debug(`codex: model catalog unavailable (${errorText(error)})`)),
+                hub.call(CLIENT.collaborationModeList, {}).catch(error => {
+                    if (rpcCode(error) === RPC_ERROR.methodNotFound || rpcCode(error) === RPC_ERROR.invalidParams)
+                        planSupported = false;
+                    else
+                        deps.debug(`codex: collaboration modes unavailable (${errorText(error)})`);
+                }),
+            ]);
+        },
+        /** Knobs not yet applied by a turn (or an idle settings update). */
+        turnOverrides() { sentOverrides = { ...pending }; return sentOverrides; },
+        /** A refused turn did not apply its settings. Drop only unsupported Plan. */
+        turnFailed(error, overrides) {
+            sentOverrides = undefined;
+            if (rpcCode(error) !== RPC_ERROR.invalidParams || rec(overrides.collaborationMode) === undefined)
+                return;
+            const warn = planSupported;
+            planSupported = false;
+            delete pending.collaborationMode;
+            settings.collaborationMode = appliedCollaboration;
+            const modeId = appliedCollaboration?.mode === 'plan' ? 'plan' : settings.permissionMode ?? 'custom';
+            if (settings.modeId !== modeId) {
+                settings.modeId = modeId;
+                deps.emit([{ type: 'mode.changed', modeId }]);
+            }
+            prefs.write({ plan: modeId === 'plan' });
+            if (warn)
+                deps.emit([{ type: 'notice', level: 'warning', key: 'codex-plan-unavailable', text: t('codex-capability-unavailable', { feature: t('codex-mode-plan') }) }]);
+        },
+        note(method, params) {
+            if (method === NOTIFY.modelVerification || method === NOTIFY.accountUpdated) {
+                catalog.rows = undefined;
+            }
+            if (method === NOTIFY.threadSettingsUpdated)
+                acknowledge(rec(params.threadSettings) ?? {});
+            if (method === NOTIFY.turnStarted && sentOverrides !== undefined) {
+                acknowledge(sentOverrides);
+                sentOverrides = undefined;
+            }
+            if (method === NOTIFY.threadTokenUsageUpdated) {
+                const usage = rec(params.tokenUsage);
+                const used = num(rec(usage?.last)?.totalTokens);
+                if (used !== undefined)
+                    context.used = used;
+                context.max = num(usage?.modelContextWindow) ?? context.max;
+            }
+            if (method === NOTIFY.threadNameUpdated) {
+                const title = str(params.threadName);
+                if (title !== undefined)
+                    deps.emit([{ type: 'session.title', title, source: title === requestedTitle ? 'user' : 'auto' }]);
+                requestedTitle = undefined;
+                return true;
+            }
+            return false;
+        },
+        get planSupported() { return planSupported; },
+    };
+}

package/lib/types/backends/codex/session/goals.d.ts

@@ -0,0 +1,25 @@
+import type { AgentEvent, AgentEventOf } from '../../../agent/events.js';
+import { type Rec } from '../narrow.js';
+import type { CodexHub } from '../rpc/hub.js';
+/** Pure mapping of the native goal snapshot (shared by get, set and notices). */
+export declare function codexGoalEvent(raw: unknown, operation?: string): AgentEventOf<'goal.change'> | undefined;
+export declare function createCodexGoals(deps: {
+    readonly hub: Pick<CodexHub, 'call'>;
+    threadId(): string;
+    emit(events: readonly AgentEvent[]): void;
+    debug?(message: string): void;
+}): {
+    readonly capability: {
+        set(objective: string, options?: {
+            readonly tokenBudget?: number;
+        }): Promise<void>;
+        pause(): Promise<void>;
+        resume(): Promise<void>;
+        clear(): Promise<void>;
+    } | undefined;
+    initialize(): Promise<void>;
+    notification(method: string, params: Rec): boolean;
+    reset(): void;
+    close(): void;
+};
+//# sourceMappingURL=goals.d.ts.map

package/lib/types/backends/codex/session/goals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goals.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/session/goals.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAExE,OAAO,EAAiB,KAAK,GAAG,EAAE,MAAM,cAAc,CAAA;AAEtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAG7C,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,SAAW,GAAG,YAAY,CAAC,aAAa,CAAC,GAAG,SAAS,CAmB1G;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACpC,QAAQ,IAAI,MAAM,CAAA;IAClB,IAAI,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAAA;IACzC,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;;;gCAwDwmW,CAAC;;;;;;kBAxBllW,OAAO,CAAC,IAAI,CAAC;yBAeZ,MAAM,UAAU,GAAG,GAAG,OAAO;aAKzC,IAAI;aACJ,IAAI;EAEhB"}

package/lib/types/backends/codex/session/goals.js

@@ -0,0 +1,97 @@
+import { t } from '../../../i18n.js';
+import { num, rec, str } from '../narrow.js';
+import { CLIENT, NOTIFY } from '../protocol/index.js';
+import { rpcCode, RPC_ERROR } from '../rpc/client.js';
+/** Pure mapping of the native goal snapshot (shared by get, set and notices). */
+export function codexGoalEvent(raw, operation = 'update') {
+    if (raw === null)
+        return { type: 'goal.change', operation: 'clear' };
+    const goal = rec(raw);
+    const threadId = str(goal?.threadId);
+    const objective = str(goal?.objective);
+    const status = str(goal?.status);
+    if (goal === undefined || threadId === undefined || objective === undefined || status === undefined)
+        return undefined;
+    const phase = status === 'usageLimited' || status === 'budgetLimited' ? 'blocked' : status;
+    if (phase !== 'active' && phase !== 'paused' && phase !== 'blocked' && phase !== 'complete')
+        return undefined;
+    return {
+        type: 'goal.change', operation,
+        goal: {
+            id: 'codex-goal:' + threadId + ':' + String(goal.createdAt),
+            revision: num(goal.updatedAt) ?? 0,
+            objective, phase, maxGoalRounds: 0,
+            ...(phase !== 'blocked' ? {} : { blockedReason: { code: status, message: t(status === 'usageLimited' ? 'codex-goal-usage-limited' : status === 'budgetLimited' ? 'codex-goal-budget-limited' : 'codex-goal-blocked') } }),
+            budget: { tokensUsed: num(goal.tokensUsed) ?? 0, tokenBudget: num(goal.tokenBudget) ?? null, timeUsedSeconds: num(goal.timeUsedSeconds) ?? 0 },
+        },
+    };
+}
+export function createCodexGoals(deps) {
+    let generation = 0;
+    let closed = false;
+    let enabled = true;
+    let signature;
+    const publish = (raw, operation) => {
+        const event = codexGoalEvent(raw, operation);
+        if (event === undefined)
+            return;
+        const next = JSON.stringify(event.goal ?? null);
+        if (next === signature)
+            return;
+        signature = next;
+        deps.emit([event]);
+    };
+    const update = async (params, operation) => {
+        const root = deps.threadId();
+        const epoch = generation;
+        const response = rec(await deps.hub.call(CLIENT.threadGoalSet, { threadId: root, ...params }));
+        if (!closed && epoch === generation && root === deps.threadId())
+            publish(response?.goal, operation);
+    };
+    const capability = {
+        set: (objective, options) => update({ objective, status: 'active', ...(options?.tokenBudget === undefined ? {} : { tokenBudget: options.tokenBudget }) }, 'set'),
+        pause: () => update({ status: 'paused' }, 'pause'),
+        resume: () => update({ status: 'active' }, 'resume'),
+        async clear() {
+            const root = deps.threadId();
+            const epoch = generation;
+            await deps.hub.call(CLIENT.threadGoalClear, { threadId: root });
+            if (!closed && epoch === generation && root === deps.threadId())
+                publish(null);
+        },
+    };
+    return {
+        get capability() { return enabled && !closed ? capability : undefined; },
+        async initialize() {
+            if (closed || !enabled)
+                return;
+            const root = deps.threadId();
+            const epoch = generation;
+            try {
+                const response = rec(await deps.hub.call(CLIENT.threadGoalGet, { threadId: root }));
+                if (!closed && epoch === generation && root === deps.threadId())
+                    publish(response?.goal);
+            }
+            catch (error) {
+                if (closed || epoch !== generation || root !== deps.threadId())
+                    return;
+                if (rpcCode(error) === RPC_ERROR.methodNotFound || rpcCode(error) === RPC_ERROR.invalidParams) {
+                    if (enabled)
+                        deps.emit([{ type: 'notice', level: 'warning', key: 'codex-goals-unsupported', text: t('codex-goals-unsupported') }]);
+                    enabled = false;
+                }
+                else
+                    deps.debug?.('codex: initial goal unavailable (' + (error instanceof Error ? error.message : String(error)) + ')');
+            }
+        },
+        notification(method, params) {
+            if (method !== NOTIFY.threadGoalUpdated && method !== NOTIFY.threadGoalCleared)
+                return false;
+            if (!closed && str(params.threadId) === deps.threadId())
+                publish(method === NOTIFY.threadGoalCleared ? null : params.goal);
+            return true;
+        },
+        reset() { generation += 1; signature = undefined; },
+        close() { closed = true; generation += 1; },
+    };
+}

package/lib/types/backends/codex/session/history.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The replay seed of a resumed thread (docs/codex-backend-design.md §5.12):
+ * the newest page of turns, which `thread/resume` returns in full when asked
+ * (`initialTurnsPage` with `itemsView: 'full'`, C0 V4), oldest first through
+ * the shared replay. A single asynchronously prefetched page makes the
+ * transcript capability synchronous; live numbering is never touched by it.
+ */
+import type { SessionCapabilities } from '../../../agent/capabilities.js';
+import type { AgentEvent, AgentEventOf } from '../../../agent/events.js';
+import { type Rec } from '../narrow.js';
+import type { CodexHub } from '../rpc/hub.js';
+import { type ItemContext } from '../translate/items.js';
+/** Turns the first page replays. */
+export declare const HISTORY_PAGE_TURNS = 20;
+/** The `initialTurnsPage` request of `thread/resume`. */
+export declare const INITIAL_TURNS_PAGE: {
+    readonly limit: 20;
+    readonly sortDirection: "desc";
+    readonly itemsView: "full";
+};
+/** The resume answer's first page as events (advancing `ctx`), and the
+ *  cursor of the next older page. */
+export declare function replayResumePage(response: Rec, ctx: ItemContext): {
+    readonly events: readonly AgentEvent[];
+    readonly olderCursor?: string;
+};
+export interface CodexTranscriptHistory {
+    takeInitial(): readonly AgentEvent[];
+    readonly capability: NonNullable<SessionCapabilities['transcript']>;
+    /** Replace the paging snapshot; the caller owns live/backfill numbering. */
+    reset(response: Rec): void;
+    /** Capture completed native facts, not deltas or optimistic tool state. */
+    notification(method: string, params: Rec): void;
+    /** Native order, including a ready prefetch page (fork/rewind lookup). */
+    readonly turns: readonly Rec[];
+    /** Find the turn immediately before the turn containing an item anchor. */
+    previousTurnId(anchor: string): string | undefined;
+    close(): void;
+}
+export interface CodexTranscriptHistoryDeps {
+    readonly hub: Pick<CodexHub, 'call'>;
+    readonly threadId: string;
+    readonly cwd: string;
+    readonly response: Rec;
+    /** Only initial replay advances the live translator context. */
+    readonly ctx: ItemContext;
+    readonly notice?: (event: AgentEventOf<'notice'>) => void;
+}
+/** A synchronous bounded record over native full items, with one older page
+ * ready ahead of the user. No I/O, decoding, or live seq changes on older(). */
+export declare function createCodexTranscriptHistory(deps: CodexTranscriptHistoryDeps): CodexTranscriptHistory;
+//# sourceMappingURL=history.d.ts.map

package/lib/types/backends/codex/session/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/session/history.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAExE,OAAO,EAAiB,KAAK,GAAG,EAAE,MAAM,cAAc,CAAA;AAEtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAG3E,oCAAoC;AACpC,eAAO,MAAM,kBAAkB,KAAK,CAAA;AAEpC,yDAAyD;AACzD,eAAO,MAAM,kBAAkB;;;;CAAmF,CAAA;AAElH;qCACqC;AACrC,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAM3I;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,IAAI,SAAS,UAAU,EAAE,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC,CAAA;IACnE,4EAA4E;IAC5E,KAAK,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAA;IAC1B,2EAA2E;IAC3E,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,CAAA;IAC/C,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,EAAE,CAAA;IAC9B,2EAA2E;IAC3E,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAClD,KAAK,IAAI,IAAI,CAAA;CACd;AACD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAA;IACtB,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAA;CAC1D;AAKD;gFACgF;AAChF,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,0BAA0B,GAAG,sBAAsB,CAiJrG"}