@adecore/agents 0.0.1 → 0.17.0-beta.2

package/dist/chat/codex-thread.d.ts

@@ -0,0 +1,32 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+import type { SpawnChatProcess } from './chat-process.ts';
+import { type CodexClientInfo } from './codex-transport.ts';
+export interface ThreadItemsParams {
+    threadId: string;
+    cursor?: string;
+    limit: number;
+    sortDirection: 'asc' | 'desc';
+}
+export declare function parseThreadItemsPage(result: unknown): {
+    entries: Record<string, unknown>[];
+    nextCursor: string | null;
+};
+export declare function projectCodexItems(entriesOldestFirst: Record<string, unknown>[], now: number): ChatItem[];
+export interface CodexProcessSpec {
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+    spawn?: SpawnChatProcess;
+    client?: CodexClientInfo;
+}
+export declare function listThreadItemsOnce(spec: CodexProcessSpec, params: ThreadItemsParams): Promise<unknown>;
+export interface ThreadForkParams {
+    threadId: string;
+    at: {
+        turnId: string;
+    } | {
+        turns: number;
+    } | null;
+    options: Record<string, unknown>;
+}
+export declare function forkThreadOnce(spec: CodexProcessSpec, params: ThreadForkParams): Promise<string>;

package/dist/chat/codex-thread.js

@@ -0,0 +1,131 @@
+import { CodexProtocol } from './codex-protocol.js';
+import { CodexTransport, DEFAULT_CODEX_CLIENT } from './codex-transport.js';
+import { ChatError } from './errors.js';
+import { readingThread, settledReading } from './subagent-projection.js';
+import { errorText } from '../error-text.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/* 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) {
+    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) {
+    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, now) {
+    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);
+}
+/* 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(spec, work) {
+    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, params) {
+    return withAppServer(spec, (transport) => transport.request('thread/items/list', params));
+}
+/* The id of the `turns`-th turn of a thread, oldest first, or null when it has fewer. */
+async function nthTurnId(transport, threadId, turns) {
+    let seen = 0;
+    let cursor = 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, params) {
+    return withAppServer(spec, async (transport) => {
+        let lastTurnId = 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;
+        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/dist/chat/codex-transport.d.ts

@@ -0,0 +1,42 @@
+import { type SpawnChatProcess } from './chat-process.ts';
+export type CodexFrame = Record<string, unknown>;
+export interface CodexClientInfo {
+    name: string;
+    title: string;
+    version: string;
+}
+export declare const DEFAULT_CODEX_CLIENT: CodexClientInfo;
+interface CodexTransportOptions {
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+    spawn?: SpawnChatProcess;
+    onFrame(frame: CodexFrame): void;
+    onError?(error: Error): void;
+    onExit(exitCode: number | null, stderr: string | null): void;
+}
+export declare class CodexTransport {
+    private readonly child;
+    private readonly options;
+    private readonly pending;
+    private nextId;
+    private closed;
+    constructor(options: CodexTransportOptions);
+    get pid(): number;
+    get alive(): boolean;
+    request(method: string, params: unknown): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    respond(id: number | string, result: unknown): void;
+    respondError(id: number | string, code: number, message: string): void;
+    end(): void;
+    kill(signal?: 'SIGTERM' | 'SIGKILL'): void;
+    stop(): void;
+    dispose(): Promise<void>;
+    private write;
+    private failed;
+    private readLine;
+    private readLines;
+    private handleLine;
+    private handleExit;
+}
+export {};

package/dist/chat/codex-transport.js

@@ -0,0 +1,188 @@
+import { errorText } from '../error-text.js';
+import { ChatChild } from './chat-process.js';
+export const DEFAULT_CODEX_CLIENT = { name: 'agents', title: 'Agents', version: '0.1.0' };
+class CodexRpcError extends Error {
+    code;
+    constructor(method, error) {
+        const detail = typeof error === 'object' && error !== null ? error : {};
+        super(`${method} failed: ${typeof detail.message === 'string' ? detail.message : JSON.stringify(error)}`);
+        this.name = 'CodexRpcError';
+        this.code = typeof detail.code === 'number' ? detail.code : null;
+    }
+}
+/*
+ * 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 {
+    child;
+    options;
+    pending = new Map();
+    nextId = 1;
+    closed = false;
+    constructor(options) {
+        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() {
+        return this.child.pid;
+    }
+    get alive() {
+        return !this.closed;
+    }
+    request(method, params) {
+        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, params) {
+        this.write({ method, params });
+    }
+    respond(id, result) {
+        this.write({ id, result });
+    }
+    respondError(id, code, message) {
+        this.write({ id, error: { code, message } });
+    }
+    /* Closes stdin; the app-server ends on its own once it has nothing more to say. */
+    end() {
+        try {
+            this.child.process.stdin.end();
+        }
+        catch {
+            // Already closed by the other side.
+        }
+    }
+    kill(signal = 'SIGTERM') {
+        this.child.process.kill(signal);
+    }
+    stop() {
+        this.end();
+        this.child.endAfterGrace();
+    }
+    dispose() {
+        return this.child.end();
+    }
+    write(frame) {
+        if (this.closed) {
+            throw new Error('Codex stdin is closed');
+        }
+        this.child.process.stdin.write(`${JSON.stringify(frame)}\n`);
+        this.child.process.stdin.flush();
+    }
+    failed(error) {
+        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));
+        }
+    }
+    readLine(line) {
+        try {
+            this.handleLine(line);
+        }
+        catch (error) {
+            this.failed(error);
+        }
+    }
+    async readLines() {
+        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();
+        }
+    }
+    handleLine(line) {
+        if (this.closed || line.trim() === '') {
+            return;
+        }
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (typeof frame !== 'object' || frame === null || Array.isArray(frame)) {
+            return;
+        }
+        const message = frame;
+        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);
+        if (message.error !== undefined) {
+            settle.reject(new CodexRpcError(settle.method, message.error));
+        }
+        else {
+            settle.resolve(message.result);
+        }
+    }
+    handleExit(exitCode, stderr) {
+        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/dist/chat/composer-preferences.d.ts

@@ -0,0 +1,15 @@
+import type { AgentKind, ChatPreferencesPayload, ModelSelection, RuntimeMode } from '@adecore/agent-contracts';
+export interface ComposerPreference {
+    runtimeMode?: RuntimeMode;
+    selection?: ModelSelection;
+    account?: string;
+}
+export declare class ComposerPreferences {
+    private readonly byClient;
+    private told;
+    set(clientId: string, preference: ChatPreferencesPayload): void;
+    forget(clientId: string): void;
+    terminalMode(): RuntimeMode | undefined;
+    for(provider: AgentKind): ComposerPreference;
+    private newest;
+}

package/dist/chat/composer-preferences.js

@@ -0,0 +1,46 @@
+/*
+ * 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 {
+    byClient = new Map();
+    told = 0;
+    set(clientId, preference) {
+        this.told += 1;
+        this.byClient.set(clientId, { preference, told: this.told });
+    }
+    forget(clientId) {
+        this.byClient.delete(clientId);
+    }
+    /* The mode the newest pick gives a terminal agent; undefined with no client or none said. */
+    terminalMode() {
+        return this.newest()?.preference.terminalRuntimeMode;
+    }
+    /* The newest pick among the connected clients, narrowed to this provider; empty with none. */
+    for(provider) {
+        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 } : {}) };
+    }
+    newest() {
+        let newest = null;
+        for (const held of this.byClient.values()) {
+            if (newest === null || isNewer(held, newest)) {
+                newest = held;
+            }
+        }
+        return newest;
+    }
+}
+function isNewer(held, than) {
+    const changedAt = held.preference.changedAt ?? 0;
+    const otherChangedAt = than.preference.changedAt ?? 0;
+    return changedAt === otherChangedAt ? held.told > than.told : changedAt > otherChangedAt;
+}

package/dist/chat/context-breakdown.d.ts

@@ -0,0 +1,2 @@
+import { type ChatContextBreakdown, type ChatItem } from '@adecore/agent-contracts';
+export declare function estimateContextBreakdown(items: readonly ChatItem[], contextTokens: number): ChatContextBreakdown;

package/dist/chat/context-breakdown.js

@@ -0,0 +1,74 @@
+import { attachmentImageMime } 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) {
+    return READ_TOOLS.has(name.slice(name.lastIndexOf('/') + 1));
+}
+function textTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+function inputTokens(input) {
+    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, contextTokens) {
+    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/dist/chat/delta-coalescer.d.ts

@@ -0,0 +1,12 @@
+import type { ChatEvent } from '@adecore/agent-contracts';
+export declare const DELTA_TICK_MS = 16;
+export declare class DeltaCoalescer {
+    private pending;
+    private timer;
+    private readonly send;
+    private readonly tickMs;
+    constructor(send: (event: ChatEvent) => void, tickMs?: number);
+    push(event: ChatEvent): void;
+    flush(): void;
+    dispose(): void;
+}

package/dist/chat/delta-coalescer.js

@@ -0,0 +1,55 @@
+/* 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 {
+    pending = null;
+    timer = null;
+    send;
+    tickMs;
+    constructor(send, tickMs = DELTA_TICK_MS) {
+        this.send = send;
+        this.tickMs = tickMs;
+    }
+    push(event) {
+        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() {
+        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() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.pending = null;
+    }
+}

package/dist/chat/errors.d.ts

@@ -0,0 +1,4 @@
+import { CodedError } from '../coded-error.ts';
+export type ChatErrorCode = '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';
+export declare class ChatError<TCode extends string = ChatErrorCode> extends CodedError<TCode> {
+}

package/dist/chat/errors.js

@@ -0,0 +1,4 @@
+import { CodedError } from '../coded-error.js';
+/* A host that refuses more than a chat does widens the codes with its own. */
+export class ChatError extends CodedError {
+}

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

@@ -0,0 +1,3 @@
+import { type FakeCli, type FakeIo, type FakeProgram } from './fake-cli.ts';
+export declare function fakeClaude(io: FakeIo): FakeProgram;
+export declare function claudeStoppingOnResume(sessionIds: ReadonlySet<string>, how: 'missing' | 'exit'): FakeCli;