Official
acp
ACP agents from the ACP registry (Gemini, Cursor, Droid, Kilo, pi, ...), Oh My Pi, and your own entries (custom.json in the plugin's data folder). Agents are discovered at runtime.
The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/acp@0.2.4
Permissions in 0.2.4
Take care. This plugin asks for permissions that can do anything your account can. The app asks you to hold Enable for two seconds or to type the plugin's name before it turns on.
Files
testing.ts9.9 KB
// Ported from the Rust plugin's agent.rs tests: notifications are routed
// straight into the agent, and the tests that drove a real RpcClient
// against a scripted Python peer drive the SDK's process transport against
// a scripted fake peer instead.
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Queue from "effect/Queue";
import * as Scope from "effect/Scope";
import * as Layer from "effect/Layer";
import * as ManagedRuntime from "effect/ManagedRuntime";
import * as z from "zod";
import { liveLayer } from "divergence/effect";
import type { PluginServices } from "divergence/effect";
import type { AgentEvent } from "divergence";
import { RpcTransport } from "../sdk/effect.ts";
import { afterEach } from "node:test";
import assert from "node:assert/strict";
import { fakeApi } from "../sdk/testing.ts";
import type { FakeOptions, FakePeer, HostScript, PeerScript, TestMessage } from "../sdk/testing.ts";
import { AcpAgent } from "./agent.ts";
import { newState } from "./state.ts";
import type { Entry } from "./registry.ts";
import type { AcpContext } from "./types.ts";
const SESSION = "sess-1";
const RUN = "run-1";
interface EntryOptions {
command?: string;
args?: string[];
env?: Record<string, string>;
mcpServers?: unknown[];
directories?: string[];
}
function entry(
id: string,
{ command = "agent", args = [], env = {}, mcpServers = [], directories = [] }: EntryOptions = {},
): Entry {
return {
id,
name: id,
description: "",
version: null,
source: { kind: "custom", command, args, env, install: null },
directories,
mcpServers,
icon: null,
iconUrl: null,
};
}
interface ContextOverrides {
which?: (program: string) => string | null | Promise<string | null>;
realPath?: (program: string) => string | null;
platform?: () => string | Promise<string>;
loginEnv?: () => Record<string, string> | Promise<Record<string, string>>;
icons?: AcpContext["icons"];
}
function context(overrides: ContextOverrides = {}): AcpContext {
return {
which: (program) =>
Effect.promise(() => Promise.resolve(overrides.which ? overrides.which(program) : `/bin/${program}`)),
realPath: (program) => Effect.succeed(overrides.realPath ? overrides.realPath(program) : program),
platform: () => Effect.promise(() => Promise.resolve(overrides.platform ? overrides.platform() : "darwin-aarch64")),
loginEnv: () => Effect.promise(() => Promise.resolve(overrides.loginEnv ? overrides.loginEnv() : {})),
icons: overrides.icons ?? {},
};
}
type PeerHandler = (params: Record<string, unknown>, message: TestMessage, peer: FakePeer) => unknown;
interface PeerOptions {
init?: Record<string, unknown>;
handlers?: Record<string, PeerHandler>;
}
/// A scripted ACP agent: answers `initialize` with `init`, every other
/// request with `handlers[method](params, message, peer)` (no answer when
/// that returns `undefined`), and a method it has no handler for with an
/// error.
function acpPeer({ init = {}, handlers = {} }: PeerOptions = {}): PeerScript {
return (message: TestMessage, peer: FakePeer) => {
if (message.method === undefined) return;
if (message.method === "initialize") {
peer.reply(message, { protocolVersion: 1, agentCapabilities: {}, authMethods: [], ...init });
return;
}
const handler = handlers[message.method];
if (!handler) {
if (message.id !== undefined)
peer.send({
jsonrpc: "2.0",
id: message.id,
error: { code: -32601, message: `unknown method ${message.method}` },
});
return;
}
const result = handler(message.params, message, peer);
if (result !== undefined) peer.reply(message, result);
};
}
type PromiseMethods<A> = {
[K in keyof A]: A[K] extends (...args: infer P) => Effect.Effect<infer R, infer _E, infer _S>
? (...args: P) => Promise<R>
: A[K];
};
type TestAgent = PromiseMethods<AcpAgent>;
type EventOf<K extends AgentEvent["event"]> = Extract<AgentEvent, { event: K }>;
function present<A>(value: A | undefined, message = "expected a value"): A {
assert.ok(value !== undefined, message);
return value;
}
function eventAt<K extends AgentEvent["event"]>(events: readonly AgentEvent[], index: number, kind: K): EventOf<K> {
const event = present(events.at(index), `expected event ${kind} at ${index}`);
assert.equal(event.event, kind);
return event as EventOf<K>;
}
function findEvent<K extends AgentEvent["event"]>(events: readonly AgentEvent[], kind: K): EventOf<K> {
const event = events.find((candidate): candidate is EventOf<K> => candidate.event === kind);
return present(event, `expected a ${kind} event`);
}
type Notification = { message: string; level: string | undefined };
interface HarnessOptions {
peer?: PeerScript;
/// A program other than the agent: its script, else the agent's `peer`.
spawn?: (program: string, args: readonly string[]) => PeerScript | undefined;
onHost?: HostScript;
fs?: FakeOptions["fs"];
agentEntry?: Entry;
ctx?: ContextOverrides;
}
const harnessCleanups = new Set<() => Promise<void>>();
afterEach(async () => {
for (const close of harnessCleanups) await close();
harnessCleanups.clear();
});
/// An agent with one session and an active run; a spawned process is the
/// scripted `peer`.
function harness(
id = "test",
{ peer = acpPeer(), spawn, onHost = () => ({}), fs, agentEntry, ctx }: HarnessOptions = {},
) {
const notifications: Notification[] = [];
const api = Object.assign(fakeApi({ onSpawn: (program, args) => spawn?.(program, args) ?? peer, onHost, fs }), {
notified: notifications,
});
api.notify = (message, level) => notifications.push({ message, level });
const events: AgentEvent[] = [];
const scope = Scope.makeUnsafe();
const runtime: ManagedRuntime.ManagedRuntime<PluginServices | RpcTransport, never> = ManagedRuntime.make(
RpcTransport.layer.pipe(
Layer.provideMerge(
liveLayer(
api,
(effect) => runtime.runPromise(effect),
() => {},
),
),
),
);
let raw: AcpAgent | undefined;
runtime.runFork(
Effect.gen(function* () {
const transport = yield* RpcTransport;
const jobs = yield* Effect.acquireRelease(
Queue.make<Effect.Effect<unknown, unknown, PluginServices>>(),
Queue.shutdown,
).pipe(Effect.provideService(Scope.Scope, scope));
const created = new AcpAgent({
entry: agentEntry ?? entry(id),
context: context(ctx),
scope,
transport,
jobs,
emit: (event) => events.push(event),
});
raw = created;
yield* created.background().pipe(Effect.provideService(Scope.Scope, scope));
}),
);
if (!raw) throw new Error("the synchronous adapter did not create the test agent");
raw.sessions.set(SESSION, newState({ live: SESSION, workspace: "/w", run: RUN }));
raw.byLive.set(SESSION, SESSION);
harnessCleanups.add(async () => {
await runtime.runPromise(Scope.close(scope, Exit.void));
await runtime.dispose();
});
const agent = new Proxy(raw, {
get(target, key, receiver) {
const value: unknown = Reflect.get(target, key, receiver);
if (typeof value !== "function") return value;
return (...args: unknown[]) => {
const result: unknown = Reflect.apply(value, target, args);
// `result` came from an AcpAgent method, and this guard proves the
// internal value is an Effect before the test runtime evaluates it.
return Effect.isEffect(result)
? runtime.runPromise(result as Effect.Effect<unknown, unknown, PluginServices>)
: result;
};
},
// The proxy only adapts AcpAgent's Effect methods to Promises; every
// other method and property keeps the AcpAgent value above unchanged.
}) as unknown as TestAgent;
return { agent, events, api, run: runtime.runPromise.bind(runtime) };
}
function update(agent: TestAgent, value: unknown, session = SESSION): void {
agent.onNotification("session/update", { sessionId: session, update: value });
}
const kinds = (events: readonly AgentEvent[]) => events.map((event) => event.event);
/// Accepts this plugin's answer to the agent's request `id` (not a request
/// of the plugin's own that happens to share the number).
const replyTo = (id: unknown) => (message: TestMessage) => message.id === id && message.method === undefined;
const errorMessageSchema = z.looseObject({ code: z.number(), message: z.string() });
function responseError(message: TestMessage) {
return errorMessageSchema.parse(message.error);
}
const requestParamsSchema = z.looseObject({
sessionId: z.string().optional(),
mcpServers: z.array(z.unknown()).optional(),
_meta: z.looseObject({ reasoningEffort: z.string().optional() }).optional(),
prompt: z.array(z.looseObject({ text: z.string().optional() })).optional(),
});
function requestParams(message: TestMessage) {
return requestParamsSchema.parse(message.params);
}
function terminalResult(message: TestMessage) {
return z.looseObject({ terminalId: z.string() }).parse(message.result);
}
export {
SESSION,
RUN,
entry,
context,
acpPeer,
present,
eventAt,
findEvent,
harness,
update,
kinds,
replyTo,
responseError,
requestParams,
terminalResult,
};
export type {
EntryOptions,
ContextOverrides,
PeerHandler,
PeerOptions,
PromiseMethods,
TestAgent,
EventOf,
Notification,
HarnessOptions,
};
/// Waits until `events` holds one that `accept` takes.
export async function next<K extends AgentEvent["event"]>(
events: readonly AgentEvent[],
kind: K,
accept: (event: EventOf<K>) => unknown = () => true,
timeout = 2000,
): Promise<EventOf<K>> {
const deadline = Date.now() + timeout;
for (;;) {
const found = events.find((event): event is EventOf<K> => event.event === kind && !!accept(event as EventOf<K>));
if (found) return found;
if (Date.now() > deadline) throw new Error(`no such event among ${JSON.stringify(kinds(events))}`);
await new Promise((resolve) => setTimeout(resolve, 5));
}
}Versions
| Version | Published | Plugin API | Size | Permissions | Status |
|---|---|---|---|---|---|
| 0.2.5latest | Nov 21, 2026 | >=5 <6 | 134 KB | 6 permissions | Listed |
| 0.2.4 | Nov 16, 2026 | >=5 <6 | 132.8 KB | 6 permissions | Listed |
| 0.2.3 | Nov 11, 2026 | >=5 <6 | 108.9 KB | 6 permissions | Listed |
| 0.2.2 | Nov 9, 2026 | >=5 <6 | 105.6 KB | 6 permissions | Listed |
| 0.2.1 | Oct 27, 2026 | >=2 <4 | 105.3 KB | 6 permissions | Listed |
No comments yet.