@adecore/agents 0.21.2 → 0.22.0

package/dist/chat/backend.d.ts

@@ -176,6 +176,10 @@ export type BackendEvent = {
     type: 'note';
     level: 'info' | 'warning' | 'error';
     text: string;
+} | {
+    type: 'stop.refused';
+    taskId: string;
+    message: string;
 } | {
     type: 'turn.done';
     promptId?: string;

package/dist/chat/chat-core.d.ts

@@ -113,6 +113,9 @@ export declare class ChatCore {
                 values?: Record<string, unknown> | undefined;
                 at: number;
             } | undefined;
+            quoteSource?: {
+                itemId: string;
+            } | undefined;
         }[] | undefined;
         queuePaused?: boolean | undefined;
         background?: {

package/dist/chat/chat-core.js

@@ -486,8 +486,9 @@ export class ChatCore {
         return result;
     }
     /*
-     * Stops one running sub-agent of the CLI's own. It cannot be stopped apart from its CLI, so its row
-     * is only marked, and only while no turn runs: stopping that turn is the composer's Stop.
+     * Stops one running sub-agent of the CLI's own. The process that started it ends it with `stop_task`
+     * and the parent keeps working. Without such a process the row is only marked, and only while no
+     * turn runs: stopping that turn is the composer's Stop.
      */
     async stopSubagent(chatId, toolUseId) {
         await this.loaded(chatId);
@@ -502,7 +503,7 @@ export class ChatCore {
         if (row.origin === 'ruimte') {
             throw new ChatError('chat-unsupported', 'This row stands for work the host runs; stop it there');
         }
-        session.markSubagentStopped(toolUseId);
+        session.stopSubagent(toolUseId);
     }
     /* Ends a command or a monitor a chat's CLI runs in the background, for a person who pressed Stop on it. */
     async stopTask(chatId, taskId) {

package/dist/chat/chat-session.d.ts

@@ -1,4 +1,4 @@
-import type { ChatAttachment, ChatAssistantItem, ChatCheckpointDiff, ChatEvent, ChatInfo, ChatItem, ChatQueuedMessage, ChatSkill, ChatUiChoiceOrigin, ChatUiChoicePayload, ChatUiQueryState, ModelSelection, RuntimeMode } from '@adecore/agent-contracts';
+import type { ChatAttachment, ChatAssistantItem, ChatCheckpointDiff, ChatEvent, ChatInfo, ChatItem, ChatQueuedMessage, ChatQuoteSource, ChatSkill, ChatUiChoiceOrigin, ChatUiChoicePayload, ChatUiQueryState, ModelSelection, RuntimeMode } from '@adecore/agent-contracts';
 import type { UiCompileOptions } from '@adecore/intelligent-ui/compiler';
 import type { ChatProvider } from '../providers/provider.ts';
 import type { LimitsUpdate } from '../usage/limits/normalize.ts';
@@ -15,6 +15,7 @@ export interface TurnCheckpoints {
         diff: ChatCheckpointDiff;
         after: string;
     } | null>;
+    head?(cwd: string): Promise<string | null>;
 }
 export interface PromptNotes {
     next(): {
@@ -72,6 +73,7 @@ export interface ChatSendExtras {
     mentions?: string[];
     skills?: string[];
     chats?: string[];
+    quoteSource?: ChatQuoteSource;
     attachments?: ChatAttachment[];
 }
 export interface ResumeWords {
@@ -101,6 +103,8 @@ export declare class ChatSession {
     private titleTimer;
     private naming;
     private frozen;
+    private readonly subagentOwners;
+    private readonly stopping;
     private readonly orphans;
     private pendingPreambles;
     private submission;
@@ -127,7 +131,7 @@ export declare class ChatSession {
         resumeAtReset?: boolean;
     }): ChatInfo;
     setAccount(account: string | undefined): ChatInfo;
-    send(text: string, extras?: ChatSendExtras): {
+    send(text: string, sent?: ChatSendExtras): {
         queued: boolean;
         turnId: string;
     };
@@ -140,6 +144,7 @@ export declare class ChatSession {
         turnId: string;
     };
     private recordUiAnswer;
+    private vetted;
     sendInput(text: string, extras?: ChatSendExtras): Promise<{
         queued: boolean;
         turnId: string;
@@ -199,6 +204,10 @@ export declare class ChatSession {
     }): Promise<unknown> | null;
     settleOrphanedSubagents(): Promise<void>;
     private recordLostBackground;
+    stopSubagent(toolUseId: string): 'stopping' | 'marked';
+    private trackSubagentOwner;
+    private refuseStop;
+    private noteStopped;
     markSubagentStopped(toolUseId: string): void;
     markSubagentsStopped(): void;
     private markStopped;

package/dist/chat/chat-session.js

@@ -70,6 +70,10 @@ export class ChatSession {
     naming = false;
     // Set while the host goes down: a CLI dying with it must not end the turn a restart takes up again.
     frozen = false;
+    // Which CLI process (generation) announced each subagent of its own, by call id; only that one can stop it.
+    subagentOwners = new Map();
+    // Subagents a stop_task went out for, as task id to call id, until their notification settles them.
+    stopping = new Map();
     // Background subagents a load found running whose transcript did not show an end yet; no CLI here will report them.
     orphans = new Set();
     pendingPreambles;
@@ -167,7 +171,8 @@ export class ChatSession {
     /*
      * Internal follow-ups wait for a new turn. User input goes through `sendInput`, which can steer native work.
      */
-    send(text, extras = {}) {
+    send(text, sent = {}) {
+        const extras = this.vetted(sent);
         const turnId = newId('turn');
         // Behind whatever still waits (a CLI that crashed leaves its queue), so everything goes out in the order it was sent.
         if (this.busy || this.queue.length > 0 || this.replacementWaits()) {
@@ -183,6 +188,7 @@ export class ChatSession {
                 ...(extras.mentions?.length ? { mentions: extras.mentions } : {}),
                 ...(extras.skills?.length ? { skills: extras.skills } : {}),
                 ...(extras.chats?.length ? { chats: extras.chats } : {}),
+                ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {}),
                 ...(extras.attachments?.length ? { attachments: extras.attachments } : {})
             };
             this.setQueue([...this.queue, message]);
@@ -278,10 +284,20 @@ export class ChatSession {
         this.options.emit(this.thread.upsert({ ...item, uiAnswers: { ...item.uiAnswers, [answer.blockId]: answer } }));
         this.options.persist();
     }
+    /* A quote whose source is no reply of this thread is sent as the plain text it is; the message itself is never refused for it. */
+    vetted(extras) {
+        if (extras.quoteSource === undefined || this.thread.get(extras.quoteSource.itemId)?.kind === 'assistant') {
+            return extras;
+        }
+        const plain = { ...extras };
+        delete plain.quoteSource;
+        return plain;
+    }
     sendInput(text, extras = {}) {
         return this.submitInput(text, extras);
     }
-    async submitInput(text, extras) {
+    async submitInput(text, sent) {
+        const extras = this.vetted(sent);
         const backend = this.backend;
         const turnId = this.info.activeTurnId;
         if (extras.delivery !== 'steer' ||
@@ -323,7 +339,8 @@ export class ChatSession {
                     mentions: extras.mentions,
                     skills: extras.skills,
                     chats: references.ids,
-                    attachments: extras.attachments
+                    attachments: extras.attachments,
+                    ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {})
                 }),
                 this.thread.patchInfo({ queue: this.queue.filter((entry) => entry.id !== message.id) })
             ]);
@@ -406,7 +423,14 @@ export class ChatSession {
         this.sendAfterReplacement = false;
         this.pauseQueue(false);
         this.setQueue(rest);
-        this.dispatch(next.text, { mentions: next.mentions, skills: next.skills, chats: next.chats, attachments: next.attachments, uiChoice: next.uiChoice }, next.turnId);
+        this.dispatch(next.text, {
+            mentions: next.mentions,
+            skills: next.skills,
+            chats: next.chats,
+            attachments: next.attachments,
+            uiChoice: next.uiChoice,
+            quoteSource: next.quoteSource
+        }, next.turnId);
     }
     dispatch(text, extras, requestedTurnId) {
         this.pauseQueue(false);
@@ -1016,6 +1040,96 @@ export class ChatSession {
         const text = `The machine restarted before background work "${label}" completed. It will not send a result. Do not wait for it.`;
         this.deliverNote({ noteId: `lost-background-${item.id}`, note: text, preamble: text });
     }
+    /*
+     * Stops one subagent of the CLI's own. The process that announced it ends it with `stop_task` and the
+     * parent goes on; a process that did not start it has nothing to address, so while a turn runs that
+     * is refused, and otherwise the row is only marked.
+     */
+    stopSubagent(toolUseId) {
+        const row = this.thread.find('subagent', (item) => item.toolUseId === toolUseId);
+        const agentId = row?.native?.agentId;
+        const owned = this.subagentOwners.get(toolUseId) === this.generation;
+        if (agentId !== undefined && owned && this.backend?.stopTask) {
+            this.stopping.set(agentId, toolUseId);
+            this.backend.stopTask(agentId);
+            return 'stopping';
+        }
+        if (agentId !== undefined && !owned && this.thread.info.activeTurnId !== null) {
+            throw new ChatError('subagent-stale', 'This sub-agent belongs to a process that has ended');
+        }
+        this.markSubagentStopped(toolUseId);
+        return 'marked';
+    }
+    trackSubagentOwner(generation, event) {
+        if (event.type === 'task.started' && event.taskId) {
+            this.subagentOwners.set(event.ref, generation);
+        }
+        else if (event.type === 'task.done') {
+            this.noteStopped(event);
+            if (event.ref !== null) {
+                this.subagentOwners.delete(event.ref);
+            }
+        }
+        else if (event.type === 'exit') {
+            this.stopping.clear();
+        }
+    }
+    /* The CLI would not stop it: with no turn running the row is only marked, and while one runs a note says it still goes on. */
+    refuseStop(agentId, message) {
+        const toolUseId = this.stopping.get(agentId);
+        if (toolUseId === undefined) {
+            return;
+        }
+        this.stopping.delete(agentId);
+        const row = this.thread.find('subagent', (item) => item.toolUseId === toolUseId);
+        if (row?.status !== 'running') {
+            return;
+        }
+        if (this.thread.info.activeTurnId === null) {
+            this.markSubagentStopped(toolUseId);
+            return;
+        }
+        this.emit([
+            this.thread.upsert({
+                id: `stop-refused-${toolUseId}-${Date.now()}`,
+                kind: 'note',
+                createdAt: Date.now(),
+                turnId: null,
+                level: 'warning',
+                text: `"${row.description || row.subagentType || 'Sub-agent'}" could not be stopped: ${message}`
+            })
+        ]);
+        this.options.persist();
+    }
+    /* The line under a subagent that `stop_task` ended, once the CLI reported it settled. */
+    noteStopped(event) {
+        const stopped = [...this.stopping].find(([agentId, toolUseId]) => agentId === event.taskId || toolUseId === event.ref);
+        if (stopped === undefined) {
+            return;
+        }
+        this.stopping.delete(stopped[0]);
+        // It finished on its own just before the stop arrived; the row already says so.
+        if (event.ok) {
+            return;
+        }
+        const row = this.thread.find('subagent', (item) => item.toolUseId === stopped[1]);
+        if (!row) {
+            return;
+        }
+        const now = Date.now();
+        this.emit([
+            ...(row.status === 'running' ? [this.thread.upsert({ ...row, status: 'failed', finishedAt: now })] : []),
+            this.thread.upsert({
+                id: `stopped-${row.toolUseId}`,
+                kind: 'note',
+                createdAt: now,
+                turnId: null,
+                level: 'info',
+                text: `"${row.description || row.subagentType || 'Sub-agent'}" was stopped.`
+            })
+        ]);
+        this.options.persist();
+    }
     /*
      * Marks a subagent of the CLI's own as stopped: `failed` with a note that says what it means, since
      * no CLI stops one subagent on its own. Refused while a turn runs, which may still be waiting on it.
@@ -1121,7 +1235,8 @@ export class ChatSession {
                 skills,
                 chats,
                 attachments,
-                ...(extras.uiChoice ? { uiChoice: extras.uiChoice } : {})
+                ...(extras.uiChoice ? { uiChoice: extras.uiChoice } : {}),
+                ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {})
             }));
         }
         events.push(this.thread.patchInfo({ status: this.thread.statusFor(turnId), activeTurnId: turnId }));
@@ -1155,14 +1270,14 @@ export class ChatSession {
         if (!checkpoints) {
             return Promise.resolve();
         }
-        return checkpoints
-            .take(this.thread.info.cwd)
-            .then((tree) => {
+        const cwd = this.thread.info.cwd;
+        return Promise.all([checkpoints.take(cwd), checkpoints.head?.(cwd) ?? null])
+            .then(([tree, head]) => {
             const turn = this.thread.get(turnId);
             if (tree === null || turn?.kind !== 'turn' || turn.state !== 'running' || this.info.activeTurnId !== turnId) {
                 return;
             }
-            this.emit([this.thread.upsert({ ...turn, checkpoint: tree })]);
+            this.emit([this.thread.upsert({ ...turn, checkpoint: tree, ...(head === null ? {} : { checkpointHead: head }) })]);
         })
             .catch(() => undefined);
     }
@@ -1172,14 +1287,22 @@ export class ChatSession {
         if (turn?.kind !== 'turn' || turn.checkpoint === undefined || turn.checkpointDiff || !this.options.checkpoints) {
             return;
         }
-        void this.options.checkpoints
-            .settle(this.thread.info.cwd, turn.checkpoint)
-            .then((answer) => {
+        const { checkpoints } = this.options;
+        const cwd = this.thread.info.cwd;
+        void Promise.all([checkpoints.settle(cwd, turn.checkpoint), checkpoints.head?.(cwd) ?? null])
+            .then(([answer, head]) => {
             const settled = this.thread.get(turnId);
             if (answer === null || settled?.kind !== 'turn') {
                 return;
             }
-            this.emit([this.thread.upsert({ ...settled, checkpointDiff: answer.diff, checkpointAfter: answer.after })]);
+            this.emit([
+                this.thread.upsert({
+                    ...settled,
+                    checkpointDiff: answer.diff,
+                    checkpointAfter: answer.after,
+                    ...(head === null ? {} : { checkpointHeadAfter: head })
+                })
+            ]);
             this.options.persist();
         })
             .catch(() => undefined);
@@ -1409,6 +1532,10 @@ export class ChatSession {
             this.applyTitle(event.title);
             return;
         }
+        if (event.type === 'stop.refused') {
+            this.refuseStop(event.taskId, event.message);
+            return;
+        }
         /*
          * A CLI reports the window it was started on. A pick made since waits for the restart the next
          * send does, so its report may not put the old size back under a meter that already reads the new one.
@@ -1466,6 +1593,7 @@ export class ChatSession {
             this.awaitingBackgroundReport = true;
         }
         this.emit(projected);
+        this.trackSubagentOwner(generation, event);
         this.watchWorkflows(event);
         if (isMainAgentOutput(event)) {
             this.spokenTurnId = this.thread.info.activeTurnId;

package/dist/chat/claude-protocol.d.ts

@@ -15,6 +15,7 @@ export declare class ClaudeProtocol {
     private readonly subagentModels;
     private apiError;
     private readonly refusedWindows;
+    private readonly stopRequests;
     private readonly steerIds;
     beginSteer(promptId: string): void;
     beginPrompt(promptId: string): void;
@@ -30,6 +31,7 @@ export declare class ClaudeProtocol {
     private endBackground;
     private endWorkflow;
     stopTaskRequest(taskId: string): unknown;
+    private handleControlResponse;
     private handleStreamEvent;
     private handleAssistant;
     private handleToolProgress;

package/dist/chat/claude-protocol.js

@@ -117,6 +117,8 @@ export class ClaudeProtocol {
     // Only main-chain errors classify the turn; each plan window can refuse it independently.
     apiError = null;
     refusedWindows = new Map();
+    // The task each `stop_task` request named, so an error answer finds it again.
+    stopRequests = new Map();
     steerIds = new Set();
     beginSteer(promptId) {
         this.steerIds.add(promptId);
@@ -152,6 +154,9 @@ export class ClaudeProtocol {
             case 'control_request':
                 this.handleControlRequest(frame, events);
                 break;
+            case 'control_response':
+                this.handleControlResponse(frame, events);
+                break;
             case 'control_cancel_request': {
                 const requestId = str(frame.request_id);
                 if (requestId) {
@@ -408,7 +413,22 @@ export class ClaudeProtocol {
     }
     /* The control request that ends one task the CLI runs beside its turns. */
     stopTaskRequest(taskId) {
-        return { type: 'control_request', request_id: `stop-task-${taskId}-${Date.now()}`, request: { subtype: 'stop_task', task_id: taskId } };
+        const requestId = `stop-task-${taskId}-${Date.now()}`;
+        this.stopRequests.set(requestId, taskId);
+        return { type: 'control_request', request_id: requestId, request: { subtype: 'stop_task', task_id: taskId } };
+    }
+    /* Only a refused `stop_task` matters; every other answer is the CLI saying it took the request. */
+    handleControlResponse(frame, events) {
+        const response = isRecord(frame.response) ? frame.response : null;
+        const requestId = str(response?.request_id);
+        const taskId = requestId === null ? undefined : this.stopRequests.get(requestId);
+        if (response === null || requestId === null || taskId === undefined) {
+            return;
+        }
+        this.stopRequests.delete(requestId);
+        if (response.subtype === 'error') {
+            events.push({ type: 'stop.refused', taskId, message: str(response.error) ?? 'The CLI refused to stop it' });
+        }
     }
     handleStreamEvent(frame, events) {
         const event = frame.event;

package/dist/chat/claude-transcript.d.ts

@@ -1,4 +1,5 @@
 import type { ChatHistoryResult, ChatItem } from '@adecore/agent-contracts';
+export declare function spokenText(content: unknown): string | null;
 export interface SubagentMeta {
     agentId: string;
     toolUseId: string | null;

package/dist/chat/claude-transcript.js

@@ -12,7 +12,7 @@ function str(value) {
     return typeof value === 'string' && value !== '' ? value : null;
 }
 /* The words of a user line that somebody said, or null for a line that carries tool results. */
-function spokenText(content) {
+export function spokenText(content) {
     if (typeof content === 'string') {
         return content;
     }

package/dist/chat/errors.d.ts

@@ -1,4 +1,4 @@
 import { CodedError } from '../coded-error.ts';
-export type ChatErrorCode = 'refused-query' | 'stale-ui-query' | 'history-expired' | 'chat-not-found' | 'chat-unreadable' | 'chat-busy' | 'request-not-found' | 'chat-unsupported' | 'invalid-attachments' | 'subagent-not-found' | 'task-not-found' | 'transcript-missing' | 'transcript-format' | 'fork-failed' | 'turn-not-found' | 'item-not-found' | 'bookmark-not-found' | 'too-many-bookmarks' | 'visual-invalid' | 'visual-too-large';
+export type ChatErrorCode = 'refused-query' | 'stale-ui-query' | 'history-expired' | 'chat-not-found' | 'chat-unreadable' | 'chat-busy' | 'request-not-found' | 'chat-unsupported' | 'invalid-attachments' | 'subagent-not-found' | 'subagent-stale' | 'task-not-found' | 'transcript-missing' | 'transcript-format' | 'fork-failed' | 'turn-not-found' | 'item-not-found' | 'bookmark-not-found' | 'too-many-bookmarks' | 'visual-invalid' | 'visual-too-large';
 export declare class ChatError<TCode extends string = ChatErrorCode> extends CodedError<TCode> {
 }

package/dist/chat/external-sessions.d.ts

@@ -0,0 +1,26 @@
+export interface SessionFs {
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{
+        mtimeMs: number;
+    } | null>;
+    readHead(path: string, maxBytes: number): Promise<string>;
+}
+export interface ExternalSession {
+    provider: 'claude' | 'codex';
+    sessionId: string;
+    title: string;
+    updatedAt: number;
+    cwd: string;
+}
+export declare function listClaudeSessions({ projectsDir, folder, fs }: {
+    projectsDir: string;
+    folder: string;
+    fs: SessionFs;
+}): Promise<ExternalSession[]>;
+export declare function listCodexSessions({ sessionsDir, folder, fs, maxFiles }: {
+    sessionsDir: string;
+    folder: string;
+    fs: SessionFs;
+    maxFiles?: number;
+}): Promise<ExternalSession[]>;
+export declare function nodeSessionFs(): Promise<SessionFs>;

package/dist/chat/external-sessions.js

@@ -0,0 +1,136 @@
+import { join } from 'node:path';
+import { clipText } from '@adecore/agent-contracts';
+import { isForkOrSubagent } from '../usage/readers/codex.js';
+import { claudeProjectSlug, spokenText } from './claude-transcript.js';
+const TITLE_LENGTH = 120;
+// Claude writes hook output and attachments ahead of the first prompt, and Codex its instructions.
+const HEAD_BYTES = 256 * 1024;
+const CLAUDE_MAX_FILES = 200;
+function titleOf(text) {
+    return clipText(text.replace(/\s+/g, ' ').trim(), TITLE_LENGTH);
+}
+function records(head) {
+    const lines = head.split('\n');
+    // The head ends wherever the byte limit fell, so its last line may not parse.
+    return lines.flatMap((line) => {
+        if (line === '') {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(line);
+            return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? [parsed] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+const CLAUDE_BOOKKEEPING = new Set(['summary', 'file-history-snapshot', 'queue-operation']);
+/* A reminder or the wrapper of a slash command is written as a user line too, but nobody said it. */
+function claudePrompt(entry) {
+    if (CLAUDE_BOOKKEEPING.has(String(entry.type)) || entry.type !== 'user' || entry.isSidechain === true || entry.isMeta === true) {
+        return null;
+    }
+    const message = typeof entry.message === 'object' && entry.message !== null ? entry.message : {};
+    const said = spokenText(message.content);
+    if (said === null || said.trim() === '' || said.startsWith('<command-') || said.startsWith('<local-command-')) {
+        return null;
+    }
+    return said;
+}
+/*
+ * The conversations Claude Code kept for a folder, newest first. Only the folder's own directory is
+ * read, and only the `.jsonl` files in it, so the transcripts of subagents in `<session>/subagents` stay out.
+ * A file without a prompt somebody said is no conversation.
+ */
+export async function listClaudeSessions({ projectsDir, folder, fs }) {
+    const dir = join(projectsDir, claudeProjectSlug(folder));
+    const names = (await fs.readdir(dir)).filter((name) => name.endsWith('.jsonl'));
+    const stats = await Promise.all(names.map(async (name) => ({ name, stat: await fs.stat(join(dir, name)) })));
+    const newest = stats
+        .flatMap(({ name, stat }) => (stat === null ? [] : [{ name, mtimeMs: stat.mtimeMs }]))
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .slice(0, CLAUDE_MAX_FILES);
+    const sessions = [];
+    for (const { name, mtimeMs } of newest) {
+        const prompt = records(await fs.readHead(join(dir, name), HEAD_BYTES))
+            .map(claudePrompt)
+            .find((said) => said !== null);
+        if (prompt !== undefined && prompt !== null) {
+            sessions.push({ provider: 'claude', sessionId: name.slice(0, -'.jsonl'.length), title: titleOf(prompt), updatedAt: mtimeMs, cwd: folder });
+        }
+    }
+    return sessions;
+}
+function codexPrompt(entry) {
+    const payload = typeof entry.payload === 'object' && entry.payload !== null ? entry.payload : null;
+    if (payload === null) {
+        return null;
+    }
+    if (entry.type === 'event_msg' && payload.type === 'user_message' && typeof payload.message === 'string') {
+        return payload.message.trim() === '' ? null : payload.message;
+    }
+    return null;
+}
+/* The newest names first; the folders are named by year, month and day, and the files by when they began. */
+function newestFirst(names) {
+    return [...names].sort().reverse();
+}
+async function rolloutFiles(sessionsDir, fs, max) {
+    const files = [];
+    for (const year of newestFirst(await fs.readdir(sessionsDir))) {
+        for (const month of newestFirst(await fs.readdir(join(sessionsDir, year)))) {
+            for (const day of newestFirst(await fs.readdir(join(sessionsDir, year, month)))) {
+                const names = newestFirst((await fs.readdir(join(sessionsDir, year, month, day))).filter((name) => name.startsWith('rollout-') && name.endsWith('.jsonl')));
+                for (const name of names) {
+                    files.push(join(sessionsDir, year, month, day, name));
+                    if (files.length >= max) {
+                        return files;
+                    }
+                }
+            }
+        }
+    }
+    return files;
+}
+/*
+ * The conversations Codex kept for a folder, newest first, out of the newest `maxFiles` rollouts. A
+ * rollout counts when its first line, the session's metadata, names this folder and is no fork or subagent.
+ */
+export async function listCodexSessions({ sessionsDir, folder, fs, maxFiles = 400 }) {
+    const sessions = [];
+    for (const path of await rolloutFiles(sessionsDir, fs, maxFiles)) {
+        const entries = records(await fs.readHead(path, HEAD_BYTES));
+        const meta = entries[0];
+        const payload = meta?.type === 'session_meta' && typeof meta.payload === 'object' && meta.payload !== null ? meta.payload : null;
+        if (payload === null || payload.cwd !== folder || typeof payload.id !== 'string' || isForkOrSubagent(payload)) {
+            continue;
+        }
+        const prompt = entries.map(codexPrompt).find((said) => said !== null);
+        if (prompt === undefined || prompt === null) {
+            continue;
+        }
+        const stat = await fs.stat(path);
+        sessions.push({ provider: 'codex', sessionId: payload.id, title: titleOf(prompt), updatedAt: stat?.mtimeMs ?? 0, cwd: folder });
+    }
+    return sessions;
+}
+/* A `node:fs` behind the seam, for a host that lists the real thing. */
+export async function nodeSessionFs() {
+    const { readdir, stat, open } = await import('node:fs/promises');
+    return {
+        readdir: async (path) => readdir(path).catch(() => []),
+        stat: async (path) => stat(path).catch(() => null),
+        readHead: async (path, maxBytes) => {
+            const handle = await open(path, 'r');
+            try {
+                const buffer = Buffer.alloc(maxBytes);
+                const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+                return buffer.subarray(0, bytesRead).toString('utf8');
+            }
+            finally {
+                await handle.close();
+            }
+        }
+    };
+}