@adecore/agents 0.21.2 → 0.22.1

package/src/chat/external-sessions.ts

@@ -0,0 +1,177 @@
+import { join } from 'node:path';
+import { clipText } from '@adecore/agent-contracts';
+import { isForkOrSubagent } from '../usage/readers/codex.ts';
+import { claudeProjectSlug, spokenText } from './claude-transcript.ts';
+
+/* What the listing may do to the file system; a fake in tests, `node:fs` in a host. */
+export interface SessionFs {
+    /* The names in a folder; empty when it is not there. */
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{ mtimeMs: number } | null>;
+    /* The first `maxBytes` of a file as text; the last line may be cut short. */
+    readHead(path: string, maxBytes: number): Promise<string>;
+}
+
+/* A conversation a CLI keeps on disk, started outside the app that lists it. */
+export interface ExternalSession {
+    provider: 'claude' | 'codex';
+    sessionId: string;
+    /* The first thing the person said, on one line. */
+    title: string;
+    updatedAt: number;
+    cwd: string;
+}
+
+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: string): string {
+    return clipText(text.replace(/\s+/g, ' ').trim(), TITLE_LENGTH);
+}
+
+function records(head: string): Array<Record<string, unknown>> {
+    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: unknown = JSON.parse(line);
+            return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? [parsed as Record<string, unknown>] : [];
+        } 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: Record<string, unknown>): string | null {
+    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 as Record<string, unknown>) : {};
+    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 }: { projectsDir: string; folder: string; fs: SessionFs }): Promise<ExternalSession[]> {
+    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: ExternalSession[] = [];
+    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: Record<string, unknown>): string | null {
+    const payload = typeof entry.payload === 'object' && entry.payload !== null ? (entry.payload as Record<string, unknown>) : 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: string[]): string[] {
+    return [...names].sort().reverse();
+}
+
+async function rolloutFiles(sessionsDir: string, fs: SessionFs, max: number): Promise<string[]> {
+    const files: string[] = [];
+    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
+}: {
+    sessionsDir: string;
+    folder: string;
+    fs: SessionFs;
+    maxFiles?: number;
+}): Promise<ExternalSession[]> {
+    const sessions: ExternalSession[] = [];
+    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 as Record<string, unknown>) : 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(): Promise<SessionFs> {
+    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();
+            }
+        }
+    };
+}

package/src/chat/fake-claude.ts

@@ -146,6 +146,40 @@ export function fakeClaude(io: FakeIo): FakeProgram {
     // What a background agent asked; its answer comes in after the turn that launched it, whenever a person gives one.
     let backgroundAsk: { requestId: string; command: string } | null = null;
     let slow = false;
+    // The two foreground subagents of `two subagents` that have not settled; the turn stays open until both have.
+    const openTwo = new Set<string>();
+
+    const settleTwo = (name: 'a-one' | 'a-two', stopped: boolean): void => {
+        const toolUseId = name === 'a-one' ? 'toolu_two_a' : 'toolu_two_b';
+        if (!openTwo.delete(name)) {
+            return;
+        }
+        if (stopped) {
+            out({ type: 'system', subtype: 'task_updated', task_id: name, patch: { status: 'killed', end_time: 0 }, session_id: sessionId });
+            out({
+                type: 'system',
+                subtype: 'task_notification',
+                task_id: name,
+                tool_use_id: toolUseId,
+                status: 'stopped',
+                output_file: '',
+                summary: 'Stopped',
+                session_id: sessionId
+            });
+        }
+        out({
+            type: 'user',
+            message: {
+                role: 'user',
+                content: [{ type: 'tool_result', tool_use_id: toolUseId, content: stopped ? 'Stopped' : `${name} done`, is_error: stopped }]
+            },
+            session_id: sessionId
+        });
+        if (openTwo.size === 0) {
+            assistantText('summarized B');
+            result();
+        }
+    };
 
     // The rest of a background agent once its request was answered: its call's result, its report, and the turn the CLI opens about it.
     const finishBackgroundAgent = (command: string, allowed: boolean, message: string | undefined): void => {
@@ -193,6 +227,43 @@ export function fakeClaude(io: FakeIo): FakeProgram {
             io.exit(1);
             return;
         }
+        // Two foreground subagents beside each other; the turn ends once both settled: a-two when the test runs what is put off, a-one by a `stop_task`.
+        if (text === 'two subagents') {
+            openTwo.add('a-one').add('a-two');
+            for (const [name, toolUseId] of [
+                ['a-one', 'toolu_two_a'],
+                ['a-two', 'toolu_two_b']
+            ] as const) {
+                out({
+                    type: 'assistant',
+                    message: {
+                        id: `msg_${nonce}_${++messageCounter}`,
+                        model,
+                        role: 'assistant',
+                        content: [
+                            { type: 'tool_use', id: toolUseId, name: 'Agent', input: { description: name, subagent_type: 'general-purpose', prompt: name } }
+                        ],
+                        usage
+                    },
+                    session_id: sessionId
+                });
+                out({
+                    type: 'system',
+                    subtype: 'task_started',
+                    task_id: name,
+                    tool_use_id: toolUseId,
+                    description: name,
+                    subagent_type: 'general-purpose',
+                    is_backgrounded: false,
+                    spawn_depth: 1,
+                    task_type: 'local_agent',
+                    prompt: name,
+                    session_id: sessionId
+                });
+            }
+            io.later(() => settleTwo('a-two', false));
+            return;
+        }
         if (text === 'crash loudly') {
             io.err(`${'warming up\n'.repeat(2000)}Error: the fake lost its key\n    at handleUser (fake-claude.ts)\n`);
             io.exit(1);
@@ -952,8 +1023,11 @@ export function fakeClaude(io: FakeIo): FakeProgram {
             } else if (frame.type === 'control_response') {
                 handleControlResponse(frame.response as Record<string, unknown>);
             } else if (frame.type === 'control_request') {
-                const request = frame.request as { subtype: string };
+                const request = frame.request as { subtype: string; task_id?: string };
                 out({ type: 'control_response', response: { subtype: 'success', request_id: frame.request_id, response: {} } });
+                if (request.subtype === 'stop_task' && (request.task_id === 'a-one' || request.task_id === 'a-two')) {
+                    settleTwo(request.task_id, true);
+                }
                 if (request.subtype === 'interrupt' && slow) {
                     slow = false;
                     assistantText('[interrupted]');

package/src/chat/thread-search.ts

@@ -0,0 +1,87 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+
+/* One message of a thread that holds the query, cut to a line around the match. */
+export interface ThreadHit {
+    itemId: string;
+    author: 'person' | 'agent';
+    snippet: string;
+    /* Where the match sits in `snippet`, in UTF-16 units. */
+    matchStart: number;
+    matchLength: number;
+    createdAt: number;
+    turnId: string | null;
+}
+
+export interface ThreadSearchOptions {
+    limit: number;
+}
+
+// Characters kept on each side of the match.
+const CONTEXT = 60;
+
+// Emphasis and code markers carry no meaning in a one-line snippet, where they only read as noise.
+function plain(text: string): string {
+    return text.replace(/\*{1,3}|_{2,}|`+/g, '').replace(/\s+/g, ' ');
+}
+
+// Moves a cut forward to the start of the next word, never past `limit`, so a snippet does not open on half a word.
+function wordStart(text: string, from: number, limit: number): number {
+    if (from === 0 || /\s/.test(text[from - 1]!) || /\s/.test(text[from]!)) {
+        return from;
+    }
+    const space = text.slice(from, limit).search(/\s/);
+    return space === -1 ? from : from + space + 1;
+}
+
+// Moves a cut back to the end of the previous word, never before `limit`.
+function wordEnd(text: string, to: number, limit: number): number {
+    if (to === text.length || /\s/.test(text[to - 1]!) || /\s/.test(text[to]!)) {
+        return to;
+    }
+    const space = text.slice(limit, to).search(/\s\S*$/);
+    return space === -1 ? to : limit + space;
+}
+
+function snippetOf(text: string, index: number, length: number): { snippet: string; matchStart: number; matchLength: number } {
+    const from = wordStart(text, Math.max(0, index - CONTEXT), index);
+    const to = wordEnd(text, Math.min(text.length, index + length + CONTEXT), index + length);
+    const before = `${from > 0 ? '…' : ''}${plain(text.slice(from, index))}`;
+    const match = plain(text.slice(index, index + length));
+    const after = `${plain(text.slice(index + length, to))}${to < text.length ? '…' : ''}`;
+    return { snippet: `${before}${match}${after}`, matchStart: before.length, matchLength: match.length };
+}
+
+/*
+ * The messages of a thread that hold `query`, oldest first, one hit per message. Only what a person
+ * and the agent said counts: what a subagent said (`parentToolUseId`) is not part of the conversation.
+ */
+export function searchThreadItems(items: readonly ChatItem[], query: string, { limit }: ThreadSearchOptions): ThreadHit[] {
+    if (query === '' || limit <= 0) {
+        return [];
+    }
+    const pattern = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i');
+    const hits: ThreadHit[] = [];
+    for (const item of items) {
+        if (item.kind !== 'user' && item.kind !== 'assistant') {
+            continue;
+        }
+        if (item.kind === 'assistant' && item.parentToolUseId) {
+            continue;
+        }
+        const found = pattern.exec(item.text);
+        if (found === null) {
+            continue;
+        }
+        hits.push({
+            itemId: item.id,
+            author: item.kind === 'user' ? 'person' : 'agent',
+            ...snippetOf(item.text, found.index, found[0].length),
+            createdAt: item.createdAt,
+            turnId: item.turnId
+        });
+        if (hits.length >= limit) {
+            break;
+        }
+    }
+    return hits;
+}

package/src/host/handlers.ts

@@ -63,7 +63,7 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
             chats.send(
                 payload.chatId,
                 payload.text,
-                { delivery: payload.delivery, mentions: payload.mentions, skills: payload.skills, chats: payload.chats },
+                { delivery: payload.delivery, mentions: payload.mentions, skills: payload.skills, chats: payload.chats, quoteSource: payload.quoteSource },
                 payload.attachments
             ),
         'chat.uiChoice': (payload, clientId) => chats.choose(payload, clientId),

package/src/providers/catalog.ts

@@ -43,7 +43,8 @@ export class ModelCatalog {
             badge: model.badge,
             legacy: model.legacy === true,
             isDefault: model.slug === this.data.defaultModel,
-            options: this.profileOf(model.slug)?.options ?? []
+            options: this.profileOf(model.slug)?.options ?? [],
+            ...(model.minCliVersion === undefined ? {} : { minCliVersion: model.minCliVersion })
         }));
     }
 

package/src/tasks/waiting-child.ts

@@ -1,4 +1,4 @@
-import { clipText, type ChatApprovalItem, type ChatItem, type ChatQuestionItem, type Task } from '@adecore/agent-contracts';
+import { clipText, WAITING_NOTE_PREFIX, type ChatApprovalItem, type ChatItem, type ChatQuestionItem, type Task } from '@adecore/agent-contracts';
 import type { ChatCore } from '../chat/chat-core.ts';
 import { errorText } from '../error-text.ts';
 import type { AgentEvent } from '../events.ts';
@@ -45,7 +45,7 @@ export function chatRequests(chats: Pick<ChatCore, 'get' | 'answer'>): ChatReque
 
 /* The id of the note one request of one child leaves in its parent, so delivering it twice leaves one. */
 export function waitingNoteId(childId: string, requestId: string): string {
-    return `waiting-${childId}-${requestId}`;
+    return `${WAITING_NOTE_PREFIX}${childId}-${requestId}`;
 }
 
 /*
@@ -185,7 +185,7 @@ export function waitingTexts(child: { id: string; title: string }, item: Waiting
 export interface DeliverWaitingDeps {
     request: ChatRequests['request'];
     titleFor(nodeId: string): string | null;
-    deliver(chatId: string, delivery: { noteId: string; note: string; preamble: string }): Promise<boolean>;
+    deliver(chatId: string, delivery: { noteId: string; note: string; from?: string; preamble: string }): Promise<boolean>;
     words: WaitingWords;
 }
 
@@ -201,6 +201,6 @@ export function deliverWaitingHandler(deps: DeliverWaitingDeps) {
             return;
         }
         const texts = waitingTexts({ id: childId, title: deps.titleFor(childId) ?? childId }, item, deps.words);
-        await deps.deliver(entry.target, { noteId: waitingNoteId(childId, requestId), ...texts });
+        await deps.deliver(entry.target, { noteId: waitingNoteId(childId, requestId), from: childId, ...texts });
     };
 }

package/src/usage/readers/codex.ts

@@ -79,7 +79,7 @@ function deltaOf(total: CodexCounts, previous: CodexCounts | null): CodexCounts
 }
 
 /* A thread that was forked or spawned repeats its parent's events before its own work starts. */
-function isForkOrSubagent(payload: Record<string, unknown>): boolean {
+export function isForkOrSubagent(payload: Record<string, unknown>): boolean {
     if (typeof payload.forked_from_id === 'string' || typeof payload.parent_thread_id === 'string') {
         return true;
     }