@adecore/agents 0.38.0 → 0.40.0

package/src/chat/readable-text.ts

@@ -10,9 +10,12 @@ export function readableAssistantText(item: Pick<ChatAssistantItem, 'text' | 'ui
     if (!item.ui?.length) {
         return item.text;
     }
+
     const blocks = item.ui.map((block) => {
         const frozen = item.uiQueries?.blocks[block.id];
+
         return frozen && frozen.revision === block.revision ? { ...block, fallback: frozen.fallback } : block;
     });
+
     return uiFallbackText(item.text, blocks);
 }

package/src/chat/request-summary.ts

@@ -6,10 +6,7 @@ import {
     type ChatRequestApproval,
     type ChatRequestSummary
 } from '@adecore/agent-contracts';
-
-function str(value: unknown): string | null {
-    return typeof value === 'string' ? value : null;
-}
+import { str } from '../fields.ts';
 
 // The keys a tool's input names its subject under, in the order a person would look for one.
 const SUBJECT_KEYS = ['file_path', 'notebook_path', 'path', 'url', 'query', 'pattern', 'skill', 'description'];
@@ -19,7 +16,9 @@ function cut(text: string, max: number): string {
     if (text.length <= max) {
         return text;
     }
+
     const end = /[\uD800-\uDBFF]/.test(text[max - 1] ?? '') ? max - 1 : max;
+
     return text.slice(0, end);
 }
 
@@ -32,7 +31,9 @@ function clipPath(path: string, max: number): string {
     if (path.length <= max) {
         return path;
     }
+
     const start = path.length - (max - 1);
+
     return `…${path.slice(/[\uDC00-\uDFFF]/.test(path[start] ?? '') ? start + 1 : start)}`;
 }
 
@@ -44,16 +45,20 @@ function firstLine(text: string): string {
 function clipLines(lines: readonly string[], maxLines: number, maxLength: number): { text: string; truncated: boolean } {
     const kept: string[] = [];
     let length = 0;
+
     for (const line of lines) {
         if (kept.length === maxLines || length + line.length + (kept.length > 0 ? 1 : 0) > maxLength) {
             if (kept.length === 0) {
                 return { text: cut(line, maxLength), truncated: true };
             }
+
             return { text: kept.join('\n'), truncated: true };
         }
+
         length += line.length + (kept.length > 0 ? 1 : 0);
         kept.push(line);
     }
+
     return { text: kept.join('\n'), truncated: false };
 }
 
@@ -84,19 +89,25 @@ function fileChange(toolName: string, input: Record<string, unknown>): FileChang
               (change): change is { path: string; diff: string } => isRecord(change) && typeof change.path === 'string' && typeof change.diff === 'string'
           )
         : [];
+
     if (patches.length > 0) {
         return { path: patches[0]!.path, files: patches.length, lines: changedLines(patches[0]!.diff) };
     }
+
     const path = str(input.file_path);
+
     if (path === null) {
         return null;
     }
+
     if (toolName === 'Edit') {
         return { path, files: 1, lines: replacementLines(str(input.old_string) ?? '', str(input.new_string) ?? '') };
     }
+
     if (toolName === 'Write') {
         return { path, files: 1, lines: replacementLines('', str(input.content) ?? '') };
     }
+
     if (toolName === 'MultiEdit' && Array.isArray(input.edits)) {
         return {
             path,
@@ -104,12 +115,14 @@ function fileChange(toolName: string, input: Record<string, unknown>): FileChang
             lines: input.edits.filter(isRecord).flatMap((edit) => replacementLines(str(edit.old_string) ?? '', str(edit.new_string) ?? ''))
         };
     }
+
     return null;
 }
 
 function subjectOf(input: Record<string, unknown>): string {
     const named = SUBJECT_KEYS.map((key) => str(input[key])).find((value) => value !== null && value.trim() !== '');
     const first = named ?? Object.values(input).find((value): value is string => typeof value === 'string' && value.trim() !== '') ?? '';
+
     return clip(firstLine(first), CHAT_REQUEST_LIMITS.subject);
 }
 
@@ -120,6 +133,7 @@ export function approvalSummary(item: ChatApprovalItem): ChatRequestApproval {
     const diff = change === null ? null : clipLines(change.lines, CHAT_REQUEST_LIMITS.diffLines, CHAT_REQUEST_LIMITS.diff);
     const shell = command === null ? null : clipLines(splitLines(command), CHAT_REQUEST_LIMITS.commandLines, CHAT_REQUEST_LIMITS.command);
     const truncated = diff?.truncated === true || shell?.truncated === true;
+
     return {
         toolName: clip(item.toolName, CHAT_REQUEST_LIMITS.subject),
         subject:

package/src/chat/subagent-projection.ts

@@ -27,6 +27,7 @@ function readingInfo(): ChatInfo {
 /* A thread and the projector that writes it, for a conversation read back rather than streamed. */
 export function readingThread(providerName: string, now: () => number): { thread: ChatThread; projector: ThreadProjector } {
     const thread = new ChatThread(readingInfo());
+
     return { thread, projector: new ThreadProjector(thread, { providerName, now }) };
 }
 
@@ -38,8 +39,10 @@ export function settledReading(item: ChatItem): ChatItem {
     if (item.kind === 'assistant') {
         return { ...item, turnId: null, streaming: false };
     }
+
     if (item.kind === 'thinking') {
         return { ...item, turnId: null, streaming: false, endedAt: item.endedAt ?? item.createdAt };
     }
+
     return { ...item, turnId: null };
 }

package/src/chat/subagent-reader.ts

@@ -110,22 +110,27 @@ export class SubagentReader {
 
     async read(chatId: string, toolUseId: string, cursor?: string, limit = DEFAULT_PAGE): Promise<ChatSubagentResult> {
         const chat = this.require(chatId);
+
         return chat.info.provider === 'codex' ? this.readCodex(chat, toolUseId, cursor, limit) : this.readClaude(chat, toolUseId, cursor, limit);
     }
 
     /* Every item, for an agent reading the conversation as text; a Codex thread is paged through to its start. */
     async readAll(chatId: string, toolUseId: string): Promise<ChatItem[]> {
         const chat = this.require(chatId);
+
         if (chat.info.provider !== 'codex') {
             return (await this.claudeProjection(chat, toolUseId)).items();
         }
+
         const pages: ChatItem[][] = [];
         let cursor: string | undefined;
+
         do {
             const page = await this.readCodex(chat, toolUseId, cursor, 100);
             pages.unshift(page.items);
             cursor = page.history.cursor ?? undefined;
         } while (cursor !== undefined);
+
         return pages.flat();
     }
 
@@ -135,9 +140,11 @@ export class SubagentReader {
      */
     async claudeSettlement(chatId: string, toolUseId: string): Promise<SubagentSettlement | null> {
         const chat = this.options.chat(chatId);
+
         if (!chat || chat.info.provider !== 'claude') {
             return null;
         }
+
         try {
             return await readSubagentSettlement((await this.claudeFile(chat, toolUseId)).path);
         } catch {
@@ -149,14 +156,19 @@ export class SubagentReader {
     hold(clientId: string, chatId: string, toolUseId: string): void {
         const key = holdKey(chatId, toolUseId);
         const existing = this.holds.get(key);
+
         if (existing) {
             existing.clients.add(clientId);
+
             return;
         }
+
         const chat = this.options.chat(chatId);
+
         if (!chat) {
             return;
         }
+
         const stop = chat.info.provider === 'codex' ? this.pollCodex(key, chatId, toolUseId) : this.watchClaude(key);
         this.holds.set(key, { chatId, toolUseId, clients: new Set([clientId]), stop });
     }
@@ -164,10 +176,13 @@ export class SubagentReader {
     release(clientId: string, chatId: string, toolUseId: string): void {
         const key = holdKey(chatId, toolUseId);
         const hold = this.holds.get(key);
+
         if (!hold) {
             return;
         }
+
         hold.clients.delete(clientId);
+
         if (hold.clients.size === 0) {
             this.drop(key, hold);
         }
@@ -182,17 +197,20 @@ export class SubagentReader {
     /* Forgets everything about a chat that is gone. */
     releaseChat(chatId: string): void {
         const ofChat = (key: string): boolean => key.startsWith(`${chatId}\n`);
+
         for (const [key, hold] of [...this.holds]) {
             if (ofChat(key)) {
                 this.drop(key, hold);
             }
         }
+
         for (const [key, file] of [...this.claudeFiles]) {
             if (ofChat(key)) {
                 this.claudeFiles.delete(key);
                 this.projections.delete(file.path);
             }
         }
+
         for (const map of [this.codexRows, this.codexSeen]) {
             for (const key of [...map.keys()]) {
                 if (ofChat(key)) {
@@ -209,9 +227,11 @@ export class SubagentReader {
 
     private require(chatId: string): SubagentChat {
         const chat = this.options.chat(chatId);
+
         if (!chat) {
             throw new ChatError('chat-not-found', `No chat ${chatId}`);
         }
+
         return chat;
     }
 
@@ -224,10 +244,13 @@ export class SubagentReader {
     /* Running while its row says so, whether that row is in the chat's thread or in a conversation read before. */
     private live(chat: SubagentChat, toolUseId: string, inside: ChatItem[]): boolean {
         const workflowAgent = workflowAgentIdOf(toolUseId);
+
         if (workflowAgent !== null) {
             return workflowAgentRunning(chat.items(), workflowAgent);
         }
+
         const row = findSubagent(chat.items(), toolUseId) ?? findSubagent(inside, toolUseId);
+
         return row?.kind === 'subagent' && row.status === 'running';
     }
 
@@ -235,6 +258,7 @@ export class SubagentReader {
         const projection = await this.claudeProjection(chat, toolUseId);
         const page = projection.page(limit, cursor);
         const seen = [...this.projections.values()].filter((entry) => entry.chatId === chat.info.chatId).flatMap((entry) => entry.projection.items());
+
         return {
             items: page.items,
             history: page.history,
@@ -247,31 +271,39 @@ export class SubagentReader {
     private async claudeProjection(chat: SubagentChat, toolUseId: string): Promise<TranscriptProjection> {
         const file = await this.claudeFile(chat, toolUseId);
         let entry = this.projections.get(file.path);
+
         if (!entry) {
             entry = { chatId: chat.info.chatId, projection: new TranscriptProjection(file.path) };
             this.projections.set(file.path, entry);
             this.trimProjections();
         }
+
         if (!(await entry.projection.refresh())) {
             throw new ChatError('subagent-not-found', 'Claude has not written a transcript for this subagent');
         }
+
         return entry.projection;
     }
 
     private async claudeFile(chat: SubagentChat, toolUseId: string): Promise<ClaudeFile> {
         const key = holdKey(chat.info.chatId, toolUseId);
         const known = this.claudeFiles.get(key);
+
         if (known) {
             return known;
         }
+
         const found = await this.claudeSubagentOf(chat.info, toolUseId);
+
         if (found === null) {
             throw new ChatError('subagent-not-found', 'Claude has not written a transcript for this subagent');
         }
+
         const { dir, meta } = found;
         const file = { dir, path: meta.transcript };
         this.claudeFiles.set(key, file);
         chat.noteNative(toolUseId, { agentId: meta.agentId });
+
         return file;
     }
 
@@ -279,6 +311,7 @@ export class SubagentReader {
     private trimProjections(): void {
         const held = new Set([...this.holds.values()].map((hold) => this.claudeFiles.get(holdKey(hold.chatId, hold.toolUseId))?.path));
         const idle = [...this.projections.keys()].filter((path) => !held.has(path));
+
         for (const path of idle.slice(0, Math.max(0, idle.length - MAX_IDLE_PROJECTIONS))) {
             this.projections.delete(path);
         }
@@ -292,53 +325,69 @@ export class SubagentReader {
     private async claudeSubagentOf(info: ChatInfo, toolUseId: string): Promise<{ dir: string; meta: SubagentMeta } | null> {
         const seen = new Set<string>();
         let current: ChatInfo | null = info;
+
         while (current !== null && !seen.has(current.chatId)) {
             seen.add(current.chatId);
             const sessionId = current.agentSessionId;
+
             const dir =
                 sessionId === null
                     ? null
                     : await findSubagentsDir(this.options.claudeProjectsDirOf?.(current) ?? this.options.claudeProjectsDir, current.cwd, sessionId);
+
             const workflowAgent = workflowAgentIdOf(toolUseId);
+
             if (dir !== null && workflowAgent !== null) {
                 const meta = await findWorkflowAgent(dir, workflowAgent);
+
                 if (meta !== null) {
                     return { dir: dirname(meta.transcript), meta };
                 }
             }
+
             // A grandchild has a file of its own in the same folder, found by the call that opened it like any other.
             const meta = dir === null ? undefined : (await readSubagentMetas(dir)).find((candidate) => candidate.toolUseId === toolUseId);
+
             if (dir !== null && meta !== undefined) {
                 return { dir, meta };
             }
+
             const origin: string | undefined = current.forkOf?.chatId;
             current = origin === undefined || !this.options.chatInfo ? null : await this.options.chatInfo(origin);
         }
+
         return null;
     }
 
     private async readCodex(chat: SubagentChat, toolUseId: string, cursor: string | undefined, limit: number): Promise<ChatSubagentResult> {
         const threadId = this.codexThread(chat, toolUseId);
+
         if (cursor !== undefined && !cursor.startsWith(CODEX_CURSOR)) {
             throw new ChatError('history-expired', 'The conversation changed. Reload its history.');
         }
+
         const params: ThreadItemsParams = {
             threadId,
             limit,
             sortDirection: 'desc',
             ...(cursor === undefined ? {} : { cursor: cursor.slice(CODEX_CURSOR.length) })
         };
+
         const { entries, nextCursor } = parseThreadItemsPage(await this.codexPage(chat, params));
+
         if (cursor === undefined) {
             // What a poll that starts after this read compares against, so a change in between is not lost.
             this.codexSeen.set(holdKey(chat.info.chatId, toolUseId), JSON.stringify(entries.slice(0, CODEX_POLL_ITEMS)));
         }
+
         const items = projectCodexItems([...entries].reverse(), this.now());
+
         for (const item of items) {
             if (item.kind === 'subagent') {
                 this.codexRows.set(holdKey(chat.info.chatId, item.toolUseId), item);
             }
         }
+
         return {
             items,
             history: { cursor: nextCursor === null ? null : `${CODEX_CURSOR}${nextCursor}` },
@@ -350,45 +399,58 @@ export class SubagentReader {
 
     private codexThreadOf(chat: SubagentChat, toolUseId: string): string | null {
         const row = findSubagent(chat.items(), toolUseId) ?? this.codexRows.get(holdKey(chat.info.chatId, toolUseId));
+
         return row?.kind === 'subagent' ? (row.native?.threadId ?? null) : null;
     }
 
     private codexThread(chat: SubagentChat, toolUseId: string): string {
         const threadId = this.codexThreadOf(chat, toolUseId);
+
         if (threadId === null) {
             throw new ChatError('subagent-not-found', 'Codex has not said which thread this subagent works in');
         }
+
         return threadId;
     }
 
     private async codexPage(chat: SubagentChat, params: ThreadItemsParams): Promise<unknown> {
         const running = chat.listThreadItems(params);
+
         if (running !== null) {
             return running;
         }
+
         const key = JSON.stringify(params);
         const now = this.now();
         const cached = this.codexCache.get(key);
+
         if (cached && now - cached.at < CODEX_CACHE_MS) {
             return cached.result;
         }
+
         const result = await this.listOnce(this.options.codexProcess(chat.info), params);
+
         for (const [stale, entry] of [...this.codexCache]) {
             if (now - entry.at >= CODEX_CACHE_MS) {
                 this.codexCache.delete(stale);
             }
         }
+
         this.codexCache.set(key, { at: now, result });
+
         return result;
     }
 
     /* One watch per subagents folder, however many of its transcripts are held. */
     private watchClaude(key: string): () => void {
         const file = this.claudeFiles.get(key);
+
         if (!file) {
             return () => undefined;
         }
+
         let shared = this.dirWatches.get(file.dir);
+
         if (!shared) {
             const watcher = this.seams.watch(file.dir, { recursive: false }, (_event, filename) => this.onClaudeChange(file.dir, filename));
             // A folder that disappears ends the growing, not the host.
@@ -396,10 +458,13 @@ export class SubagentReader {
             shared = { watcher, keys: new Set() };
             this.dirWatches.set(file.dir, shared);
         }
+
         shared.keys.add(key);
+
         return () => {
             const current = this.dirWatches.get(file.dir);
             current?.keys.delete(key);
+
             if (current && current.keys.size === 0) {
                 current.watcher.close();
                 this.dirWatches.delete(file.dir);
@@ -410,6 +475,7 @@ export class SubagentReader {
     private onClaudeChange(dir: string, filename: string | null): void {
         for (const key of this.dirWatches.get(dir)?.keys ?? []) {
             const path = this.claudeFiles.get(key)?.path;
+
             // A platform that names no file could mean any of them.
             if (filename === null || (path !== undefined && basename(path) === filename)) {
                 this.markChanged(key);
@@ -420,14 +486,17 @@ export class SubagentReader {
     private pollCodex(key: string, chatId: string, toolUseId: string): () => void {
         let cancel: (() => void) | null = null;
         let stopped = false;
+
         const tick = async (): Promise<void> => {
             cancel = null;
             const chat = this.options.chat(chatId);
             const threadId = chat ? this.codexThreadOf(chat, toolUseId) : null;
             const asked = chat && threadId ? chat.listThreadItems({ threadId, limit: CODEX_POLL_ITEMS, sortDirection: 'desc' }) : null;
+
             if (asked !== null) {
                 try {
                     const seen = JSON.stringify(parseThreadItemsPage(await asked).entries);
+
                     if (!stopped && this.codexSeen.get(key) !== seen) {
                         this.codexSeen.set(key, seen);
                         this.markChanged(key);
@@ -436,11 +505,14 @@ export class SubagentReader {
                     // The process went between the question and the answer; the next tick asks again.
                 }
             }
+
             if (!stopped) {
                 cancel = this.seams.schedule(() => tick(), CODEX_POLL_MS);
             }
         };
+
         cancel = this.seams.schedule(() => tick(), CODEX_POLL_MS);
+
         return () => {
             stopped = true;
             cancel?.();
@@ -449,9 +521,11 @@ export class SubagentReader {
 
     private markChanged(key: string): void {
         this.changed.add(key);
+
         if (this.cancelSettle !== null) {
             return;
         }
+
         this.cancelSettle = this.seams.schedule(() => this.flushChanged(), CHANGE_SETTLE_MS);
     }
 
@@ -459,8 +533,10 @@ export class SubagentReader {
         this.cancelSettle = null;
         const keys = [...this.changed];
         this.changed.clear();
+
         for (const key of keys) {
             const hold = this.holds.get(key);
+
             for (const clientId of hold?.clients ?? []) {
                 this.options.notify(clientId, { chatId: hold!.chatId, toolUseId: hold!.toolUseId });
             }

package/src/chat/subagent-settlement.ts

@@ -14,20 +14,25 @@ export interface SubagentSettlement {
 function handbackBefore(lines: string[], end: number): string | null {
     for (let i = end - 1; i >= 0; i--) {
         let entry: unknown;
+
         try {
             entry = JSON.parse(lines[i]!);
         } catch {
             continue;
         }
+
         const message = isRecord(entry) && entry.type === 'assistant' && isRecord(entry.message) ? entry.message : null;
         const content = message && Array.isArray(message.content) ? message.content.filter(isRecord) : [];
+
         for (const block of content) {
             const input = block.type === 'tool_use' && block.name === 'SubagentHandback' && isRecord(block.input) ? block.input : null;
+
             if (input && typeof input.message === 'string' && input.message.trim() !== '') {
                 return input.message;
             }
         }
     }
+
     return null;
 }
 
@@ -42,36 +47,48 @@ export function settlementOf(text: string): SubagentSettlement | null {
     if (!text.endsWith('\n')) {
         return null;
     }
+
     const lines = text.split('\n');
+
     for (let i = lines.length - 1; i >= 0; i--) {
         const line = lines[i]!.trim();
+
         if (line === '') {
             continue;
         }
+
         let entry: unknown;
+
         try {
             entry = JSON.parse(line);
         } catch {
             return null;
         }
+
         if (!isRecord(entry) || (entry.type !== 'user' && entry.type !== 'assistant')) {
             continue;
         }
+
         const message = isRecord(entry.message) ? entry.message : {};
         const content = Array.isArray(message.content) ? message.content.filter(isRecord) : [];
+
         if (entry.type !== 'assistant' || message.stop_reason !== 'end_turn' || content.some((block) => block.type === 'tool_use')) {
             return null;
         }
+
         const time = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN;
         const handedBack = handbackBefore(lines, i);
+
         const report =
             handedBack ??
             content
                 .map((block) => (block.type === 'text' && typeof block.text === 'string' ? block.text : ''))
                 .filter((part) => part.trim() !== '')
                 .join('\n');
+
         return { finishedAt: Number.isFinite(time) ? time : null, report: report === '' ? null : report };
     }
+
     return null;
 }
 
@@ -81,14 +98,17 @@ export function settlementOf(text: string): SubagentSettlement | null {
  */
 export async function readSubagentSettlement(path: string): Promise<SubagentSettlement | null> {
     let before: { size: number; mtimeMs: number };
+
     try {
         before = await stat(path);
     } catch {
         return null;
     }
+
     const from = Math.max(0, before.size - TAIL_BYTES);
     const handle = await open(path, 'r');
     let text: string;
+
     try {
         const bytes = Buffer.alloc(before.size - from);
         const { bytesRead } = await handle.read(bytes, 0, bytes.length, from);
@@ -96,13 +116,17 @@ export async function readSubagentSettlement(path: string): Promise<SubagentSett
     } finally {
         await handle.close();
     }
+
     const after = await stat(path).catch(() => null);
+
     if (after === null || after.size !== before.size || after.mtimeMs !== before.mtimeMs) {
         return null;
     }
+
     if (from > 0) {
         const start = text.indexOf('\n');
         text = start < 0 ? '' : text.slice(start + 1);
     }
+
     return text === '' ? null : settlementOf(text);
 }

package/src/chat/thread-search.ts

@@ -29,7 +29,9 @@ 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;
 }
 
@@ -38,7 +40,9 @@ 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;
 }
 
@@ -48,6 +52,7 @@ function snippetOf(text: string, index: number, length: number): { snippet: stri
     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 };
 }
 
@@ -59,19 +64,25 @@ export function searchThreadItems(items: readonly ChatItem[], query: string, { l
     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',
@@ -79,9 +90,11 @@ export function searchThreadItems(items: readonly ChatItem[], query: string, { l
             createdAt: item.createdAt,
             turnId: item.turnId
         });
+
         if (hits.length >= limit) {
             break;
         }
     }
+
     return hits;
 }