@adecore/agents 0.29.3 → 0.31.0

package/dist/chat/acp-backend.d.ts

@@ -0,0 +1,59 @@
+import { type ModelSelection } from '@adecore/agent-contracts';
+import { type AcpModeMap, type AcpSessionInfo } from './acp-protocol.ts';
+import type { ApprovalDecision, BackendHost, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
+export interface AcpClientInfo {
+    name: string;
+    title?: string;
+    version: string;
+}
+export declare const DEFAULT_ACP_CLIENT: AcpClientInfo;
+export interface AcpAgentSpec {
+    name: string;
+    env?: Record<string, string>;
+    modes?: AcpModeMap;
+    authMethod?: string | null;
+    loginHint?: string;
+    client?: AcpClientInfo;
+    model?(selection: ModelSelection): string | null;
+    onSession?(info: AcpSessionInfo): void;
+}
+export declare class AcpBackend implements ChatBackend {
+    private readonly launch;
+    private readonly host;
+    private readonly spec;
+    private readonly client;
+    private readonly protocol;
+    private transport;
+    private capabilities;
+    private sessionId;
+    private replaying;
+    private contextPending;
+    private prompt;
+    constructor(launch: BackendLaunch, host: BackendHost, spec: AcpAgentSpec);
+    get running(): boolean;
+    get pid(): number | null;
+    start(): Promise<void>;
+    private handshake;
+    private sessionParams;
+    private openSession;
+    private authenticated;
+    private applyMode;
+    private applyModel;
+    private applyThoughtLevel;
+    private promptBlocks;
+    sendTurn(input: TurnInput): void;
+    compact(): void;
+    interrupt(): void;
+    respondApproval(requestId: string, decision: ApprovalDecision): boolean;
+    respondQuestion(): boolean;
+    declineRequest(requestId: string): boolean;
+    stop(): void;
+    dispose(): Promise<void>;
+    private respond;
+    private fail;
+    private handleFrame;
+    private handleExit;
+    private emitAll;
+    private emit;
+}
+export declare function createAcpBackend(spec: AcpAgentSpec): (launch: BackendLaunch, host: BackendHost) => ChatBackend;

package/dist/chat/acp-backend.js

@@ -0,0 +1,407 @@
+import { readFileSync } from 'node:fs';
+import { attachmentImageMime } from '@adecore/agent-contracts';
+import { errorText } from '../error-text.js';
+import { MODE_ORDER } from '../modes.js';
+import { ACP_AUTH_REQUIRED, ACP_PROTOCOL_VERSION, AcpProtocol, acpStopWords, autoAllows, parseInitialize, parseSessionInfo, resolveAcpMode, runtimeModeOf, sessionIdOf } from './acp-protocol.js';
+import { attachmentNote } from './input.js';
+import { JsonRpcError, JsonRpcTransport } from './json-rpc-transport.js';
+export const DEFAULT_ACP_CLIENT = { name: 'agents', title: 'Agents', version: '0.1.0' };
+// What `initialize` and a session request may take; a prompt and a login wait for as long as the agent runs.
+const REQUEST_TIMEOUT_MS = 60_000;
+function nameOf(client) {
+    return client.title ?? client.name;
+}
+/*
+ * One ACP agent process on JSON-RPC over stdio. `start` runs `initialize` and opens the session
+ * (new, or the chat's own resumed or loaded), sets the mode and the model, and only then takes a turn.
+ * A turn is one `session/prompt` request and ends on its response. The client advertises no file
+ * system and no terminal, so the agent works with its own tools.
+ */
+export class AcpBackend {
+    launch;
+    host;
+    spec;
+    client;
+    protocol;
+    transport = null;
+    capabilities = null;
+    sessionId = '';
+    // A loaded session replays its history as updates the thread already holds.
+    replaying = false;
+    contextPending = null;
+    prompt = null;
+    constructor(launch, host, spec) {
+        this.launch = launch;
+        this.host = host;
+        this.spec = spec;
+        this.client = spec.client ?? DEFAULT_ACP_CLIENT;
+        this.protocol = new AcpProtocol(launch.generation, spec.modes ?? {}, acpStopWords(spec.name));
+    }
+    get running() {
+        return this.transport !== null;
+    }
+    get pid() {
+        return this.transport?.pid ?? null;
+    }
+    async start() {
+        if (this.transport) {
+            return;
+        }
+        const transport = new JsonRpcTransport({
+            command: this.launch.command,
+            cwd: this.launch.cwd,
+            env: { ...this.launch.env, ...this.spec.env },
+            ...(this.launch.spawn ? { spawn: this.launch.spawn } : {}),
+            label: this.spec.name,
+            errorName: 'AcpRpcError',
+            requestTimeoutMs: REQUEST_TIMEOUT_MS,
+            versionField: true,
+            onError: (error) => this.fail(error),
+            onFrame: (frame) => this.handleFrame(transport, frame),
+            onExit: (exitCode, stderr) => this.handleExit(transport, exitCode, stderr)
+        });
+        this.transport = transport;
+        try {
+            await this.handshake(transport);
+        }
+        catch (error) {
+            // A chat that failed to start drops this backend, so nothing else would end an agent stuck in its handshake.
+            if (this.transport === transport) {
+                this.transport = null;
+                void transport.dispose();
+            }
+            throw error;
+        }
+    }
+    async handshake(transport) {
+        const capabilities = parseInitialize(await transport.request('initialize', {
+            protocolVersion: ACP_PROTOCOL_VERSION,
+            clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+            clientInfo: { name: this.client.name, title: nameOf(this.client), version: this.client.version }
+        }));
+        if (capabilities.protocolVersion !== ACP_PROTOCOL_VERSION) {
+            throw new Error(`${this.spec.name} speaks ACP version ${capabilities.protocolVersion}; only version ${ACP_PROTOCOL_VERSION} is supported`);
+        }
+        this.capabilities = capabilities;
+        const info = await this.openSession(transport, capabilities);
+        const modeId = await this.applyMode(transport, info);
+        const model = await this.applyModel(transport, info);
+        await this.applyThoughtLevel(transport, info);
+        this.spec.onSession?.(info);
+        this.emit({
+            type: 'session',
+            agentSessionId: this.sessionId,
+            model,
+            effectiveRuntimeMode: this.launch.runtimeMode,
+            ...(modeId === null ? {} : { permissionMode: modeId })
+        });
+    }
+    sessionParams() {
+        const folders = this.launch.folders ?? [];
+        return {
+            cwd: this.launch.cwd,
+            mcpServers: [],
+            ...(folders.length > 0 && this.capabilities?.additionalDirectories ? { additionalDirectories: folders } : {})
+        };
+    }
+    async openSession(transport, capabilities) {
+        const resume = this.launch.resume;
+        if (resume) {
+            const method = capabilities.resumeSession ? 'session/resume' : capabilities.loadSession ? 'session/load' : null;
+            if (method === null) {
+                this.emit({ type: 'note', level: 'warning', text: `${this.spec.name} cannot continue a session it ran before. Started a new one.` });
+            }
+            else {
+                try {
+                    this.replaying = method === 'session/load';
+                    const result = await this.authenticated(transport, method, { sessionId: resume, ...this.sessionParams() });
+                    this.sessionId = resume;
+                    this.contextPending = [this.launch.resumeInstructions ?? null, this.launch.resumeNote].filter((part) => part !== null).join('\n\n') || null;
+                    return parseSessionInfo(result, resume, capabilities.agent);
+                }
+                catch (error) {
+                    // A refusal means the agent no longer has the session and a fresh one keeps the chat usable; a silence or an exit says nothing about it.
+                    if (!(error instanceof JsonRpcError)) {
+                        throw error;
+                    }
+                    this.emit({
+                        type: 'note',
+                        level: 'warning',
+                        text: `${this.spec.name} could not continue its session (${errorText(error)}). Started a new one.`
+                    });
+                }
+                finally {
+                    this.replaying = false;
+                }
+            }
+        }
+        const result = await this.authenticated(transport, 'session/new', this.sessionParams());
+        const sessionId = sessionIdOf(result);
+        if (sessionId === null) {
+            throw new Error(`session/new failed: ${this.spec.name} answered without a session id`);
+        }
+        this.sessionId = sessionId;
+        this.contextPending = this.launch.instructions;
+        return parseSessionInfo(result, sessionId, capabilities.agent);
+    }
+    /* A session request, once more after `authenticate` when the agent says it needs a login first. */
+    async authenticated(transport, method, params) {
+        try {
+            return await transport.request(method, params);
+        }
+        catch (error) {
+            if (!(error instanceof JsonRpcError) || error.code !== ACP_AUTH_REQUIRED) {
+                throw error;
+            }
+            const methodId = this.spec.authMethod ?? null;
+            const offered = this.capabilities?.authMethods ?? [];
+            if (methodId === null || (offered.length > 0 && !offered.includes(methodId))) {
+                throw new Error(`${this.spec.name} is not signed in.${this.spec.loginHint ? ` ${this.spec.loginHint}` : ''}`, { cause: error });
+            }
+            await transport.request('authenticate', { methodId }, { timeoutMs: null });
+            return transport.request(method, params);
+        }
+    }
+    /* Puts the session in the agent mode the runtime mode maps to; answers the mode it runs in, or null for an agent without modes. */
+    async applyMode(transport, info) {
+        const modes = info.modes;
+        if (modes === null || modes.modes.length === 0) {
+            return null;
+        }
+        const map = this.spec.modes ?? {};
+        const requested = this.launch.runtimeMode;
+        const resolved = resolveAcpMode(requested, map, modes.modes.map((mode) => mode.id));
+        if (resolved === null) {
+            const current = runtimeModeOf(modes.current, map);
+            if (current !== null && MODE_ORDER.indexOf(current) > MODE_ORDER.indexOf(requested)) {
+                throw new Error(`${this.spec.name} runs in ${modes.current}, which allows more than ${requested}, and offers no narrower mode`);
+            }
+            return modes.current;
+        }
+        if (resolved.modeId === modes.current) {
+            return modes.current;
+        }
+        if (modes.configId === null) {
+            await transport.request('session/set_mode', { sessionId: this.sessionId, modeId: resolved.modeId });
+        }
+        else {
+            await transport.request('session/set_config_option', { sessionId: this.sessionId, configId: modes.configId, value: resolved.modeId });
+        }
+        return resolved.modeId;
+    }
+    /* Switches to the selected model where the agent offers it; answers the model the session runs. */
+    async applyModel(transport, info) {
+        const models = info.models;
+        const wanted = this.spec.model ? this.spec.model(this.launch.selection) : this.launch.selection.model;
+        if (models === null || wanted === null || wanted === models.current) {
+            return models?.current ?? wanted;
+        }
+        if (!models.models.some((model) => model.id === wanted)) {
+            this.emit({ type: 'note', level: 'warning', text: `${this.spec.name} does not offer ${this.launch.modelName}. It runs ${models.current}.` });
+            return models.current;
+        }
+        try {
+            if (models.configId === null) {
+                await transport.request('session/set_model', { sessionId: this.sessionId, modelId: wanted });
+            }
+            else {
+                await transport.request('session/set_config_option', { sessionId: this.sessionId, configId: models.configId, value: wanted });
+            }
+            return wanted;
+        }
+        catch (error) {
+            if (!(error instanceof JsonRpcError)) {
+                throw error;
+            }
+            this.emit({
+                type: 'note',
+                level: 'warning',
+                text: `${this.spec.name} did not switch to ${this.launch.modelName} (${errorText(error)}). It runs ${models.current}.`
+            });
+            return models.current;
+        }
+    }
+    async applyThoughtLevel(transport, info) {
+        const level = info.thoughtLevel;
+        const effort = this.launch.selection.options.effort;
+        if (level === null || typeof effort !== 'string' || effort === level.current || !level.values.includes(effort)) {
+            return;
+        }
+        await transport.request('session/set_config_option', { sessionId: this.sessionId, configId: level.configId, value: effort }).catch((error) => {
+            if (!(error instanceof JsonRpcError)) {
+                throw error;
+            }
+        });
+    }
+    promptBlocks(input) {
+        const sendsImages = this.capabilities?.images === true;
+        const images = sendsImages ? input.attachments.filter((attachment) => attachmentImageMime(attachment) !== null) : [];
+        const blocks = images.map((attachment) => {
+            let data;
+            try {
+                data = readFileSync(attachment.path).toString('base64');
+            }
+            catch {
+                throw new Error(`Could not read attached image "${attachment.name}". Attach it again and retry.`);
+            }
+            return { type: 'image', mimeType: attachmentImageMime(attachment), data };
+        });
+        const named = input.attachments.filter((attachment) => !images.includes(attachment));
+        const parts = [this.contextPending, input.preamble, input.text, attachmentNote(named)].filter((part) => part !== null && part !== '');
+        this.contextPending = null;
+        return [{ type: 'text', text: parts.join('\n\n') }, ...blocks];
+    }
+    sendTurn(input) {
+        const transport = this.transport;
+        if (!transport) {
+            this.emit({ type: 'failed', message: `session/prompt failed: ${this.spec.name} is not running` });
+            return;
+        }
+        const prompt = this.promptBlocks(input);
+        const turn = { promptId: input.promptId, cancelled: false };
+        this.prompt = turn;
+        transport
+            .request('session/prompt', { sessionId: this.sessionId, prompt }, { timeoutMs: null })
+            .then((result) => {
+            if (this.transport === transport && this.prompt === turn) {
+                this.prompt = null;
+                this.emitAll(this.protocol.finish(turn.cancelled ? { stopReason: 'cancelled' } : result, turn.promptId));
+            }
+        })
+            .catch((error) => {
+            // A process that went has its exit tell the thread; anything else ends this turn alone.
+            if (this.transport === transport && transport.alive && this.prompt === turn) {
+                this.prompt = null;
+                this.emitAll(this.protocol.abort(turn.promptId, turn.cancelled ? null : errorText(error)));
+            }
+        });
+    }
+    /* ACP has no call to fold the context; a host that offers it sends the agent's own command as a prompt. */
+    compact() {
+        this.emit({ type: 'note', level: 'warning', text: `${this.spec.name} cannot fold its context on request.` });
+        this.emit({ type: 'turn.done', state: 'done', costUsd: 0 });
+    }
+    /* Cancels the turn: every permission request still open is answered as cancelled, and the turn ends on the prompt's response. */
+    interrupt() {
+        const transport = this.transport;
+        if (!transport) {
+            return;
+        }
+        if (this.prompt === null) {
+            this.emit({ type: 'turn.done', state: 'aborted', costUsd: 0 });
+            return;
+        }
+        this.prompt.cancelled = true;
+        try {
+            for (const cancelled of this.protocol.cancelPermissions()) {
+                transport.respond(cancelled.rpcId, cancelled.result);
+                this.emit({ type: 'request.withdrawn', requestId: cancelled.requestId });
+            }
+            transport.notify('session/cancel', { sessionId: this.sessionId });
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    respondApproval(requestId, decision) {
+        const answer = this.protocol.answer(requestId, decision);
+        if (!answer) {
+            return false;
+        }
+        return this.respond(requestId, answer.rpcId, answer.result);
+    }
+    /* ACP asks no questions of its own; an agent asks in its message and the next prompt answers. */
+    respondQuestion() {
+        return false;
+    }
+    declineRequest(requestId) {
+        return this.protocol.hasPermission(requestId) && this.respondApproval(requestId, 'deny');
+    }
+    stop() {
+        this.transport?.stop();
+    }
+    dispose() {
+        const transport = this.transport;
+        this.transport = null;
+        return transport?.dispose() ?? Promise.resolve();
+    }
+    respond(requestId, rpcId, result) {
+        try {
+            if (!this.transport) {
+                throw new Error(`${this.spec.name} is not running`);
+            }
+            this.transport.respond(rpcId, result);
+            return true;
+        }
+        catch (error) {
+            this.emit({ type: 'request.withdrawn', requestId });
+            this.fail(error);
+            return false;
+        }
+    }
+    fail(error) {
+        this.emit({ type: 'failed', message: errorText(error), processAlive: this.running });
+    }
+    handleFrame(transport, frame) {
+        if (this.transport !== transport) {
+            return;
+        }
+        const id = typeof frame.id === 'number' || typeof frame.id === 'string' ? frame.id : null;
+        if (frame.method === 'session/update' && id === null) {
+            if (!this.replaying) {
+                this.emitAll(this.protocol.update(this.sessionId, frame.params));
+            }
+            return;
+        }
+        if (id === null) {
+            return;
+        }
+        if (frame.method !== 'session/request_permission') {
+            transport.respondError(id, -32601, `${nameOf(this.client)} does not handle ${String(frame.method)}`);
+            return;
+        }
+        const permission = this.protocol.permission(id, this.sessionId, frame.params);
+        if (permission === null) {
+            transport.respondError(id, -32602, 'Not a permission request of this session');
+            return;
+        }
+        if (this.prompt?.cancelled) {
+            this.emitAll(permission.events.filter((event) => event.type !== 'approval.requested'));
+            const answer = this.protocol.cancelPermissions().find((cancelled) => cancelled.requestId === permission.requestId);
+            if (answer) {
+                transport.respond(answer.rpcId, answer.result);
+            }
+            return;
+        }
+        if (autoAllows(this.launch.runtimeMode, permission.kind)) {
+            this.emitAll(permission.events.filter((event) => event.type !== 'approval.requested'));
+            const answer = this.protocol.answer(permission.requestId, 'allow');
+            if (answer) {
+                this.respond(permission.requestId, answer.rpcId, answer.result);
+            }
+            return;
+        }
+        this.emitAll(permission.events);
+    }
+    handleExit(transport, exitCode, stderr) {
+        if (this.transport !== transport) {
+            return;
+        }
+        this.transport = null;
+        this.prompt = null;
+        this.protocol.cancelPermissions();
+        this.emit({ type: 'exit', exitCode, ...(stderr === null ? {} : { stderr }) });
+    }
+    emitAll(events) {
+        for (const event of events) {
+            this.emit(event);
+        }
+    }
+    emit(event) {
+        this.host.onEvent(event);
+    }
+}
+/* The `createBackend` of a provider whose agent speaks ACP. */
+export function createAcpBackend(spec) {
+    return (launch, host) => new AcpBackend(launch, host, spec);
+}

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

@@ -0,0 +1,131 @@
+import { type ChatFileChange, type RuntimeMode } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import type { ApprovalDecision, BackendEvent } from './backend.ts';
+export declare const ACP_PROTOCOL_VERSION = 1;
+export declare const ACP_AUTH_REQUIRED = -32000;
+declare const DiffSchema: z.ZodObject<{
+    type: z.ZodLiteral<"diff">;
+    path: z.ZodString;
+    oldText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    newText: z.ZodString;
+}, z.core.$loose>;
+export interface AcpAgentInfo {
+    name: string;
+    title: string | null;
+    version: string;
+}
+export interface AcpAgentCapabilities {
+    protocolVersion: number;
+    loadSession: boolean;
+    resumeSession: boolean;
+    additionalDirectories: boolean;
+    images: boolean;
+    authMethods: string[];
+    agent: AcpAgentInfo | null;
+}
+export declare function parseInitialize(result: unknown): AcpAgentCapabilities;
+export interface AcpModel {
+    id: string;
+    name: string;
+    description: string | null;
+}
+export interface AcpModelState {
+    current: string;
+    models: AcpModel[];
+    configId: string | null;
+}
+export interface AcpMode {
+    id: string;
+    name: string;
+}
+export interface AcpModeState {
+    current: string;
+    modes: AcpMode[];
+    configId: string | null;
+}
+export interface AcpSessionInfo {
+    sessionId: string;
+    agent: AcpAgentInfo | null;
+    models: AcpModelState | null;
+    modes: AcpModeState | null;
+    thoughtLevel: {
+        configId: string;
+        current: string;
+        values: string[];
+    } | null;
+}
+export declare function parseSessionInfo(result: unknown, sessionId: string, agent: AcpAgentInfo | null): AcpSessionInfo;
+export declare function sessionIdOf(result: unknown): string | null;
+export type AcpModeMap = Partial<Record<RuntimeMode, readonly string[]>>;
+export declare function resolveAcpMode(requested: RuntimeMode, map: AcpModeMap, offered: readonly string[]): {
+    modeId: string;
+    runtimeMode: RuntimeMode;
+} | null;
+export declare function runtimeModeOf(modeId: string, map: AcpModeMap): RuntimeMode | null;
+export declare function autoAllows(mode: RuntimeMode, kind: string | null): boolean;
+export declare function unifiedDiff(oldText: string, newText: string): string | null;
+type Diff = z.infer<typeof DiffSchema>;
+interface ToolState {
+    title: string;
+    name: string | null;
+    kind: string | null;
+    status: string | null;
+    rawInput: unknown;
+    rawOutput: unknown;
+    locations: string[];
+    diffs: Diff[];
+    text: string[];
+    shown: string | null;
+    settled: boolean;
+}
+export declare function toolRow(tool: Pick<ToolState, 'title' | 'name' | 'kind' | 'rawInput' | 'locations' | 'diffs'>): {
+    name: string;
+    input: Record<string, unknown>;
+    changes?: ChatFileChange[];
+};
+export interface AcpPermission {
+    requestId: string;
+    rpcId: number | string;
+    kind: string | null;
+    events: BackendEvent[];
+}
+export interface AcpStopWords {
+    maxTokens: string;
+    maxTurnRequests: string;
+    refusal: string;
+}
+export declare function acpStopWords(agentName: string): AcpStopWords;
+export declare class AcpProtocol {
+    private readonly generation;
+    private readonly modes;
+    private readonly words;
+    private readonly tools;
+    private readonly permissions;
+    private text;
+    private thought;
+    private counter;
+    private costUsd;
+    constructor(generation: number, modes: AcpModeMap, words: AcpStopWords);
+    update(sessionId: string, params: unknown): BackendEvent[];
+    modeEvent(modeId: string): BackendEvent;
+    permission(rpcId: number | string, sessionId: string, params: unknown): AcpPermission | null;
+    answer(requestId: string, decision: ApprovalDecision): {
+        rpcId: number | string;
+        result: unknown;
+    } | null;
+    cancelPermissions(): Array<{
+        requestId: string;
+        rpcId: number | string;
+        result: unknown;
+    }>;
+    hasPermission(requestId: string): boolean;
+    finish(result: unknown, promptId: string | undefined): BackendEvent[];
+    abort(promptId: string | undefined, error: string | null): BackendEvent[];
+    private messageChunk;
+    private thoughtChunk;
+    private closeText;
+    private closeThought;
+    private toolCall;
+    private plan;
+}
+export {};