@adecore/agents 0.0.1 → 0.17.0-beta.1

package/src/chat/codex-thread.ts

@@ -0,0 +1,162 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+import type { SpawnChatProcess } from './chat-process.ts';
+import { CodexProtocol } from './codex-protocol.ts';
+import { CodexTransport, DEFAULT_CODEX_CLIENT, type CodexClientInfo } from './codex-transport.ts';
+import { ChatError } from './errors.ts';
+import { readingThread, settledReading } from './subagent-projection.ts';
+import { errorText } from '../error-text.ts';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export interface ThreadItemsParams {
+    threadId: string;
+    cursor?: string;
+    limit: number;
+    sortDirection: 'asc' | 'desc';
+}
+
+/* One `thread/items/list` answer as far as a reader needs it: the entries newest first, and the cursor to older ones. */
+export function parseThreadItemsPage(result: unknown): { entries: Record<string, unknown>[]; nextCursor: string | null } {
+    const data = isRecord(result) && Array.isArray(result.data) ? result.data.filter(isRecord) : [];
+    const nextCursor = isRecord(result) && typeof result.nextCursor === 'string' && result.nextCursor !== '' ? result.nextCursor : null;
+    return { entries: data, nextCursor };
+}
+
+function userText(content: unknown): string {
+    return Array.isArray(content)
+        ? content
+              .filter(isRecord)
+              .map((block) => (typeof block.text === 'string' ? block.text : ''))
+              .filter((text) => text !== '')
+              .join('\n')
+        : '';
+}
+
+/*
+ * Items of a Codex thread, oldest first, through the mapping the live stream uses. Every entry is
+ * projected on its own: consecutive reasoning would otherwise become one thinking item whose id
+ * depends on where a page happened to start, and a client merging two reads by id would show that
+ * thought twice.
+ */
+export function projectCodexItems(entriesOldestFirst: Record<string, unknown>[], now: number): ChatItem[] {
+    const { thread, projector } = readingThread('Codex', () => now);
+    const protocol = new CodexProtocol(0);
+    for (const entry of entriesOldestFirst) {
+        const item = isRecord(entry.item) ? entry.item : null;
+        if (!item || typeof item.id !== 'string') {
+            continue;
+        }
+        projector.reset();
+        if (item.type === 'userMessage') {
+            const text = userText(item.content);
+            if (text !== '') {
+                thread.upsert({ id: `user-${item.id}`, kind: 'user', createdAt: now, turnId: null, text });
+            }
+            continue;
+        }
+        for (const event of protocol.handle({ method: 'item/completed', params: { item } })) {
+            projector.project(0, event);
+        }
+    }
+    return thread.list().map(settledReading);
+}
+
+export interface CodexProcessSpec {
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+    spawn?: SpawnChatProcess;
+    client?: CodexClientInfo;
+}
+
+/* An app-server started for the questions `work` asks and ended after them, for a chat whose own process may not run. */
+async function withAppServer<T>(spec: CodexProcessSpec, work: (transport: CodexTransport) => Promise<T>): Promise<T> {
+    const transport = new CodexTransport({
+        command: spec.command,
+        cwd: spec.cwd,
+        env: spec.env,
+        ...(spec.spawn ? { spawn: spec.spawn } : {}),
+        onFrame: () => undefined,
+        onExit: () => undefined
+    });
+    try {
+        await transport.request('initialize', {
+            clientInfo: spec.client ?? DEFAULT_CODEX_CLIENT,
+            capabilities: { experimentalApi: true, requestAttestation: false }
+        });
+        transport.notify('initialized', {});
+        return await work(transport);
+    } finally {
+        transport.end();
+        transport.kill('SIGTERM');
+    }
+}
+
+/*
+ * A page asked of an app-server started for this one question, for a chat whose own process is not
+ * running. The app-server reads a thread it never loaded from disk (checked against codex-cli 0.154.0),
+ * so nothing has to be resumed first.
+ */
+export function listThreadItemsOnce(spec: CodexProcessSpec, params: ThreadItemsParams): Promise<unknown> {
+    return withAppServer(spec, (transport) => transport.request('thread/items/list', params));
+}
+
+export interface ThreadForkParams {
+    threadId: string;
+    /* The turn the fork goes on after; null for all of it. */
+    at: { turnId: string } | { turns: number } | null;
+    /* The thread options the fork runs with: `cwd`, `model` and what the runtime mode says. */
+    options: Record<string, unknown>;
+}
+
+/* The id of the `turns`-th turn of a thread, oldest first, or null when it has fewer. */
+async function nthTurnId(transport: CodexTransport, threadId: string, turns: number): Promise<string | null> {
+    let seen = 0;
+    let cursor: string | null = null;
+    do {
+        const page = await transport.request('thread/turns/list', { threadId, limit: 100, sortDirection: 'asc', ...(cursor === null ? {} : { cursor }) });
+        const data = isRecord(page) && Array.isArray(page.data) ? page.data.filter(isRecord) : [];
+        for (const turn of data) {
+            if (++seen === turns) {
+                return typeof turn.id === 'string' ? turn.id : null;
+            }
+        }
+        cursor = isRecord(page) && typeof page.nextCursor === 'string' && page.nextCursor !== '' ? page.nextCursor : null;
+    } while (cursor !== null);
+    return null;
+}
+
+/*
+ * A new thread with the turns of `threadId` up to the one named, through `thread/fork`, and its id.
+ * Asked of a process of its own even while the chat's backend holds the thread: measured against
+ * codex-cli 0.154.0, with the original answering on in its own process afterwards.
+ */
+export function forkThreadOnce(spec: CodexProcessSpec, params: ThreadForkParams): Promise<string> {
+    return withAppServer(spec, async (transport) => {
+        let lastTurnId: string | null = null;
+        if (params.at !== null) {
+            lastTurnId = 'turnId' in params.at ? params.at.turnId : await nthTurnId(transport, params.threadId, params.at.turns);
+            if (lastTurnId === null) {
+                throw new ChatError('turn-not-found', 'Codex keeps fewer turns in this thread than the chat shows, so the turn could not be found');
+            }
+        }
+        let result: unknown;
+        try {
+            result = await transport.request('thread/fork', {
+                threadId: params.threadId,
+                excludeTurns: true,
+                ...params.options,
+                ...(lastTurnId === null ? {} : { lastTurnId })
+            });
+        } catch (error) {
+            throw new ChatError('fork-failed', errorText(error));
+        }
+        const thread = isRecord(result) && isRecord(result.thread) ? result.thread : null;
+        if (thread === null || typeof thread.id !== 'string' || thread.id === '') {
+            throw new ChatError('fork-failed', 'Codex answered the fork without a thread');
+        }
+        return thread.id;
+    });
+}

package/src/chat/codex-transport.ts

@@ -0,0 +1,224 @@
+import { errorText } from '../error-text.ts';
+import { ChatChild, type SpawnChatProcess } from './chat-process.ts';
+
+export type CodexFrame = Record<string, unknown>;
+
+/* How the host names itself in the `initialize` every app-server is opened with. */
+export interface CodexClientInfo {
+    name: string;
+    title: string;
+    version: string;
+}
+
+export const DEFAULT_CODEX_CLIENT: CodexClientInfo = { name: 'agents', title: 'Agents', version: '0.1.0' };
+
+interface CodexTransportOptions {
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+    spawn?: SpawnChatProcess;
+    // Notifications and server requests; responses to our own requests settle their promise instead.
+    onFrame(frame: CodexFrame): void;
+    onError?(error: Error): void;
+    // `stderr` is the tail of what the app-server wrote there, for an exit with an error code only.
+    onExit(exitCode: number | null, stderr: string | null): void;
+}
+
+class CodexRpcError extends Error {
+    readonly code: number | null;
+
+    constructor(method: string, error: unknown) {
+        const detail = typeof error === 'object' && error !== null ? (error as { message?: unknown; code?: unknown }) : {};
+        super(`${method} failed: ${typeof detail.message === 'string' ? detail.message : JSON.stringify(error)}`);
+        this.name = 'CodexRpcError';
+        this.code = typeof detail.code === 'number' ? detail.code : null;
+    }
+}
+
+type Settle = { resolve(value: unknown): void; reject(reason: Error): void; method: string };
+
+/*
+ * One `codex app-server` process and the JSON-RPC framing on its stdio: newline-delimited JSON,
+ * a request carries an id and gets a result or an error back under the same id, a notification
+ * has no id. The app-server also sends requests of its own (approvals), answered with `respond`.
+ */
+export class CodexTransport {
+    private readonly child: ChatChild;
+    private readonly options: CodexTransportOptions;
+    private readonly pending = new Map<number, Settle>();
+    private nextId = 1;
+    private closed = false;
+
+    constructor(options: CodexTransportOptions) {
+        this.options = options;
+        this.child = new ChatChild({
+            command: options.command,
+            cwd: options.cwd,
+            env: options.env,
+            ...(options.spawn ? { spawn: options.spawn } : {}),
+            onError: (error) => this.failed(error),
+            onExit: (exitCode, stderr) => this.handleExit(exitCode, stderr)
+        });
+        void this.readLines();
+    }
+
+    get pid(): number {
+        return this.child.pid;
+    }
+
+    get alive(): boolean {
+        return !this.closed;
+    }
+
+    request(method: string, params: unknown): Promise<unknown> {
+        return new Promise((resolve, reject) => {
+            if (this.closed) {
+                reject(new Error(`${method} failed: Codex is not running`));
+                return;
+            }
+            const id = this.nextId++;
+            this.pending.set(id, { resolve, reject, method });
+            try {
+                this.write({ id, method, params });
+            } catch (error) {
+                this.pending.delete(id);
+                reject(error);
+            }
+        });
+    }
+
+    notify(method: string, params: unknown): void {
+        this.write({ method, params });
+    }
+
+    respond(id: number | string, result: unknown): void {
+        this.write({ id, result });
+    }
+
+    respondError(id: number | string, code: number, message: string): void {
+        this.write({ id, error: { code, message } });
+    }
+
+    /* Closes stdin; the app-server ends on its own once it has nothing more to say. */
+    end(): void {
+        try {
+            this.child.process.stdin.end();
+        } catch {
+            // Already closed by the other side.
+        }
+    }
+
+    kill(signal: 'SIGTERM' | 'SIGKILL' = 'SIGTERM'): void {
+        this.child.process.kill(signal);
+    }
+
+    stop(): void {
+        this.end();
+        this.child.endAfterGrace();
+    }
+
+    dispose(): Promise<void> {
+        return this.child.end();
+    }
+
+    private write(frame: CodexFrame): void {
+        if (this.closed) {
+            throw new Error('Codex stdin is closed');
+        }
+        this.child.process.stdin.write(`${JSON.stringify(frame)}\n`);
+        this.child.process.stdin.flush();
+    }
+
+    private failed(error: unknown): void {
+        const failure = new Error(`Codex transport failed: ${errorText(error)}`);
+        for (const settle of this.pending.values()) {
+            settle.reject(failure);
+        }
+        this.pending.clear();
+        try {
+            this.options.onError?.(failure);
+        } catch (reportError) {
+            console.error('Reporting a Codex transport failure failed:', errorText(reportError));
+        }
+    }
+
+    private readLine(line: string): void {
+        try {
+            this.handleLine(line);
+        } catch (error) {
+            this.failed(error);
+        }
+    }
+
+    private async readLines(): Promise<void> {
+        const reader = this.child.process.stdout.getReader();
+        const decoder = new TextDecoder();
+        let buffered = '';
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done) {
+                    break;
+                }
+                buffered += decoder.decode(value, { stream: true });
+                let newline = buffered.indexOf('\n');
+                while (newline >= 0) {
+                    this.readLine(buffered.slice(0, newline));
+                    buffered = buffered.slice(newline + 1);
+                    newline = buffered.indexOf('\n');
+                }
+            }
+            if (buffered.trim() !== '') {
+                this.readLine(buffered);
+            }
+        } catch (error) {
+            if (!this.closed) {
+                this.failed(error);
+            }
+        } finally {
+            reader.releaseLock();
+        }
+    }
+
+    private handleLine(line: string): void {
+        if (this.closed || line.trim() === '') {
+            return;
+        }
+        let frame: unknown;
+        try {
+            frame = JSON.parse(line);
+        } catch {
+            return;
+        }
+        if (typeof frame !== 'object' || frame === null || Array.isArray(frame)) {
+            return;
+        }
+        const message = frame as CodexFrame;
+        if (typeof message.method === 'string') {
+            this.options.onFrame(message);
+            return;
+        }
+        const settle = typeof message.id === 'number' ? this.pending.get(message.id) : undefined;
+        if (!settle) {
+            return;
+        }
+        this.pending.delete(message.id as number);
+        if (message.error !== undefined) {
+            settle.reject(new CodexRpcError(settle.method, message.error));
+        } else {
+            settle.resolve(message.result);
+        }
+    }
+
+    private handleExit(exitCode: number | null, stderr: string | null): void {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        for (const settle of this.pending.values()) {
+            settle.reject(new Error(`${settle.method} failed: Codex exited`));
+        }
+        this.pending.clear();
+        this.options.onExit(exitCode, stderr);
+    }
+}

package/src/chat/composer-preferences.ts

@@ -0,0 +1,67 @@
+import type { AgentKind, ChatPreferencesPayload, ModelSelection, RuntimeMode } from '@adecore/agent-contracts';
+
+export interface ComposerPreference {
+    runtimeMode?: RuntimeMode;
+    selection?: ModelSelection;
+    // The account a new chat or agent of this CLI starts under when nothing names one.
+    account?: string;
+}
+
+interface Held {
+    preference: ChatPreferencesPayload;
+    // The order it was told in, which settles two picks with the same `changedAt`.
+    told: number;
+}
+
+/*
+ * What each connected client says a new chat starts with, for the chats the host starts with no
+ * client mounting them. Held per socket like the approval switch: a machine never remembers a
+ * person's pick after that person's client is gone, so with nobody connected a chat gets the
+ * host's own defaults.
+ */
+export class ComposerPreferences {
+    private readonly byClient = new Map<string, Held>();
+    private told = 0;
+
+    set(clientId: string, preference: ChatPreferencesPayload): void {
+        this.told += 1;
+        this.byClient.set(clientId, { preference, told: this.told });
+    }
+
+    forget(clientId: string): void {
+        this.byClient.delete(clientId);
+    }
+
+    /* The mode the newest pick gives a terminal agent; undefined with no client or none said. */
+    terminalMode(): RuntimeMode | undefined {
+        return this.newest()?.preference.terminalRuntimeMode;
+    }
+
+    /* The newest pick among the connected clients, narrowed to this provider; empty with none. */
+    for(provider: AgentKind): ComposerPreference {
+        const newest = this.newest();
+        if (newest === null) {
+            return {};
+        }
+        const { runtimeMode, selections, accounts } = newest.preference;
+        const selection = selections?.[provider];
+        const account = accounts?.[provider];
+        return { ...(runtimeMode ? { runtimeMode } : {}), ...(selection ? { selection } : {}), ...(account ? { account } : {}) };
+    }
+
+    private newest(): Held | null {
+        let newest: Held | null = null;
+        for (const held of this.byClient.values()) {
+            if (newest === null || isNewer(held, newest)) {
+                newest = held;
+            }
+        }
+        return newest;
+    }
+}
+
+function isNewer(held: Held, than: Held): boolean {
+    const changedAt = held.preference.changedAt ?? 0;
+    const otherChangedAt = than.preference.changedAt ?? 0;
+    return changedAt === otherChangedAt ? held.told > than.told : changedAt > otherChangedAt;
+}

package/src/chat/context-breakdown.ts

@@ -0,0 +1,80 @@
+import { attachmentImageMime, type ChatContextBreakdown, type ChatItem } from '@adecore/agent-contracts';
+
+// A rough rate for prose and code alike; scaling to the CLI's own total absorbs the error.
+const CHARS_PER_TOKEN = 4;
+
+// What a model is charged for a picture at the size a CLI sends it, whatever its bytes on disk.
+const IMAGE_TOKENS = 1_600;
+
+// Tools whose result is a file's contents. An MCP tool is named `<server>/<tool>`, so only the last part counts.
+const READ_TOOLS = new Set(['Read', 'NotebookRead', 'View', 'read_file', 'read_text_file', 'read_multiple_files']);
+
+function isReadTool(name: string): boolean {
+    return READ_TOOLS.has(name.slice(name.lastIndexOf('/') + 1));
+}
+
+function textTokens(text: string): number {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+function inputTokens(input: unknown): number {
+    if (input === undefined || input === null) {
+        return 0;
+    }
+    return textTokens(typeof input === 'string' ? input : JSON.stringify(input));
+}
+
+/*
+ * What the context of the last request is made of, estimated from the thread and scaled to the
+ * total the CLI reported. A subagent's own work never reached the main context, only its prompt and
+ * its report did, and nothing before the last compaction survived it. Thinking is left out: a CLI
+ * does not carry it into the next request.
+ */
+export function estimateContextBreakdown(items: readonly ChatItem[], contextTokens: number): ChatContextBreakdown {
+    let toolOutput = 0;
+    let filesRead = 0;
+    let conversation = 0;
+    const start = items.findLastIndex((item) => item.kind === 'compaction') + 1;
+    for (const item of items.slice(start)) {
+        switch (item.kind) {
+            case 'user':
+                conversation += textTokens(item.text);
+                filesRead += (item.attachments ?? []).filter((attachment) => attachmentImageMime(attachment) !== null).length * IMAGE_TOKENS;
+                break;
+            case 'assistant':
+                if (!item.parentToolUseId) {
+                    conversation += textTokens(item.text);
+                }
+                break;
+            case 'tool': {
+                if (item.parentToolUseId !== null) {
+                    break;
+                }
+                const tokens = inputTokens(item.input) + textTokens(item.output ?? item.progress?.output ?? '');
+                if (isReadTool(item.name)) {
+                    filesRead += tokens;
+                } else {
+                    toolOutput += tokens;
+                }
+                break;
+            }
+            case 'subagent':
+                // A row the host drew for work it delegated stands for that work; the call that made it is a tool row of its own.
+                if (item.origin !== 'ruimte') {
+                    toolOutput += textTokens(item.prompt ?? '') + textTokens(item.result ?? '');
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    const total = Math.max(0, Math.round(contextTokens));
+    const estimated = toolOutput + filesRead + conversation;
+    const scale = estimated > total ? total / estimated : 1;
+    const parts = {
+        toolOutput: Math.floor(toolOutput * scale),
+        filesRead: Math.floor(filesRead * scale),
+        conversation: Math.floor(conversation * scale)
+    };
+    return { ...parts, system: Math.max(0, total - parts.toolOutput - parts.filesRead - parts.conversation) };
+}

package/src/chat/delta-coalescer.ts

@@ -0,0 +1,62 @@
+import type { ChatEvent } from '@adecore/agent-contracts';
+
+/* The same rhythm as terminal output: a frame at 60 Hz. */
+export const DELTA_TICK_MS = 16;
+
+/*
+ * Holds the deltas of one chat back for a frame and sends the run on one item as a single delta. A
+ * CLI writes tens of deltas a second and every one was a frame to every client and a state update
+ * there, while the reveal on the client only moves once per frame anyway. Any other event sends
+ * what is held first, so the order a client sees is the order the thread changed in.
+ */
+export class DeltaCoalescer {
+    private pending: { itemId: string; text: string } | null = null;
+    private timer: ReturnType<typeof setTimeout> | null = null;
+    private readonly send: (event: ChatEvent) => void;
+    private readonly tickMs: number;
+
+    constructor(send: (event: ChatEvent) => void, tickMs: number = DELTA_TICK_MS) {
+        this.send = send;
+        this.tickMs = tickMs;
+    }
+
+    push(event: ChatEvent): void {
+        if (event.type !== 'delta') {
+            this.flush();
+            this.send(event);
+            return;
+        }
+        if (this.pending !== null && this.pending.itemId === event.itemId) {
+            this.pending.text += event.text;
+            return;
+        }
+        this.flush();
+        this.pending = { itemId: event.itemId, text: event.text };
+        this.timer = setTimeout(() => this.flush(), this.tickMs);
+        // A frame of text waiting must never be the reason the process stays up.
+        this.timer.unref?.();
+    }
+
+    /* Sends what is held now, before a client attaches or detaches or the tick runs out. */
+    flush(): void {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const pending = this.pending;
+        if (pending === null) {
+            return;
+        }
+        this.pending = null;
+        this.send({ type: 'delta', itemId: pending.itemId, text: pending.text });
+    }
+
+    /* Drops what is held without sending it, for a chat that is gone. */
+    dispose(): void {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.pending = null;
+    }
+}

package/src/chat/errors.ts

@@ -0,0 +1,25 @@
+import { CodedError } from '../coded-error.ts';
+
+export type ChatErrorCode =
+    | 'history-expired'
+    | 'chat-not-found'
+    // A record on disk this version cannot read, which is never written over.
+    | 'chat-unreadable'
+    | 'chat-busy'
+    | 'request-not-found'
+    | 'chat-unsupported'
+    | 'invalid-attachments'
+    | 'subagent-not-found'
+    | 'task-not-found'
+    // What reading or forking a CLI's own conversation is refused with.
+    | 'transcript-missing'
+    | 'transcript-format'
+    | 'fork-failed'
+    | 'turn-not-found'
+    // What a bookmark is refused with.
+    | 'item-not-found'
+    | 'bookmark-not-found'
+    | 'too-many-bookmarks';
+
+/* A host that refuses more than a chat does widens the codes with its own. */
+export class ChatError<TCode extends string = ChatErrorCode> extends CodedError<TCode> {}