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.5

Permissions in 0.2.5

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.
  • Run any command process.anyDangerousStarts any program or shell command. This is as strong as your own account.Start the ACP agents, which the registry launches by path or through package runners such as npx and uvx, and run the terminal commands an agent asks for
  • Provide agents agents.provideMediumAdds agents to the app.Provide the agents of the ACP registry, and serve plugin tools to them through the host's loopback MCP server
  • Network access netMediumConnects to the listed hosts.Download the ACP registry and the agents' marks once a dayHosts: cdn.agentclientprotocol.com
  • Read files fs.readMediumReads files in the listed places.Read the files an agent asks for (ACP fs/read_text_file), only inside the chat's workspace, and your own agents from custom.json in this plugin's data folderPlaces: the open workspaceits own data folder
  • Write files fs.writeMediumCreates, changes and deletes files in the listed places.Write the files an agent asks to write (ACP fs/write_text_file), only inside the chat's workspace, and move the custom agents of the old ACP plugin into custom.json oncePlaces: the open workspaceits own data folder
  • Environment variables envMediumReads the listed environment variables.Sign Grok in with your xAI API key when you set one, and tell which Windows build of an agent to runVariables: XAI_API_KEYPROCESSOR_ARCHITECTURE

Files

requests.ts13.2 KB
// Agent-to-client requests and user interaction for ACP sessions.
import * as Effect from "effect/Effect";
import * as Result from "effect/Result";
import { Fs, parse } from "divergence/effect";
import { compact, newId } from "../sdk/agent.ts";
import { RpcError, INVALID_PARAMS, methodNotFound } from "../sdk/jsonrpc.ts";
import type { RpcRequest } from "../sdk/jsonrpc.ts";
import { errorMessage } from "../sdk/errors.ts";
import { contain, parentOf, sliceLines } from "./files.ts";
import * as map from "./map.ts";
import { record } from "./entities.ts";
import { answer as extensionAnswer, question as extensionQuestion } from "./quirks.ts";
import * as wire from "./wire.ts";
import type { AcpAgent } from "./agent.ts";
import type { QuestionAnswer } from "./types.ts";
const RESOURCE_NOT_FOUND = -32002;

function isBackground(agent: AcpAgent, session: string, subject: Record<string, unknown> = {}): boolean {
  const live = agent.liveOf(session);
  const own = agent.projections.get(live)?.state.background;
  const call = record(subject.toolCall);
  if (
    Array.isArray(own) &&
    own.some((value) => {
      const item = record(value);
      return (
        (item.type === "tool_call" && item.toolCallId === (subject.toolCallId ?? call.toolCallId)) ||
        (item.type === "terminal" && item.terminalId === subject.terminalId)
      );
    })
  )
    return true;
  let child = live;
  for (
    let parent = agent.subagents.children.get(child)?.parent;
    parent !== undefined;
    parent = agent.subagents.children.get(child)?.parent
  ) {
    const background = agent.projections.get(parent)?.state.background;
    if (
      Array.isArray(background) &&
      background.some((value) => record(value).type === "subagent" && record(value).sessionId === child)
    )
      return true;
    child = parent;
  }
  return false;
}

export const handleRequest = Effect.fn("Acp.handleRequest")(function* (
  this: AcpAgent,
  { method, params, reply }: RpcRequest,
) {
  const body = yield* parse("ACP client request", this.protocol.clientSchema(method), params ?? {}).pipe(
    Effect.mapError((error) => new RpcError(INVALID_PARAMS, error.message)),
  );
  if (!this.protocol.clientMethod(method)) return reply.err(methodNotFound(method));
  switch (method) {
    case "session/request_permission":
      return yield* this.onPermission(body, reply);
    case "fs/read_text_file":
      return yield* this.onReadFile(body, reply);
    case "fs/write_text_file":
      return yield* this.onWriteFile(body, reply);
    case "terminal/create":
      return yield* this.onTerminalCreate(body, reply);
    case "terminal/output":
      return this.onTerminalOutput(body, reply);
    case "terminal/wait_for_exit":
      return yield* this.onTerminalWait(body, reply);
    case "terminal/kill":
      return yield* this.onTerminalKill(body, reply);
    case "terminal/release":
      return yield* this.onTerminalRelease(body, reply);
    case "elicitation/create":
    case "session/elicitation":
      return yield* this.onElicitation(body, reply);
    default: {
      const extension = this.quirks.extension(method);
      if (extension?.kind === "ask_question") return yield* this.onExtensionQuestion(extension.dialect, body, reply);
      if (extension?.kind === "propose_plan") return this.onExtensionPlan(extension.dialect, body, reply);
      // The notification-only extensions are never requests.
      return reply.err(methodNotFound(method));
    }
  }
});

export const onPermission = Effect.fn("Acp.onPermission")(function* (
  this: AcpAgent,
  request: wire.Message,
  reply: RpcRequest["reply"],
) {
  const session = this.hostOf(String(request.sessionId ?? ""));
  // Some agents have no way to ask a question, so they send a permission
  // request whose options are answers. Showing that as an approval card
  // offers "allow" and "reject" for a choice of three.
  if (this.quirks.permissionIsQuestion(request)) {
    const id = newId("acp-question");
    return yield* this.ask(session, id, map.permissionQuestion(id, request), reply, (answer) => {
      const chosen = answer?.values?.option;
      return !answer?.cancelled && typeof chosen === "string"
        ? { outcome: { outcome: "selected", optionId: chosen } }
        : { outcome: { outcome: "cancelled" } };
    });
  }
  const permission = this.protocol.permission(request);
  const subject = permission.subject;
  request = permission.request;
  if (subject.type === "tool_call") {
    this.dispatchUpdate(session, String(request.sessionId), {
      sessionUpdate: "tool_call_update",
      ...record(subject.toolCall),
    });
  }
  const views = this.terminals.views(String(request.sessionId ?? ""));
  const stored = this.projections
    .get(String(request.sessionId))
    ?.items.get(`tool:${record(subject.toolCall).toolCallId}`);
  const call =
    stored?.role === "tool"
      ? stored.call
      : request.toolCall && typeof request.toolCall === "object" && request.toolCall.toolCallId !== undefined
        ? map.toolCallFromUpdate(request.toolCall, views)
        : null;
  const title = (permission.title ?? call?.title) || `${this.name} needs permission`;
  // An agent can attach the warning to the request or to the one option
  // that would grant the standing right it is warning about.
  const options = Array.isArray(request.options) ? request.options : [];
  const warning =
    permission.warning ??
    map.approvalWarning(request._meta) ??
    options.map((option) => this.quirks.optionWarning(option)).find(Boolean) ??
    null;
  const id = newId("acp-approval");
  const decision = Effect.callback<string | null>((resume) => {
    this.approvals.set(id, {
      session,
      requestId: reply.id,
      background: isBackground(this, session, subject),
      resolve: (value) => resume(Effect.succeed(value)),
    });
    return Effect.sync(() => {
      this.approvals.delete(id);
    });
  });
  this.emitFor(
    session,
    compact({
      event: "approval",
      id,
      title,
      toolCall: call,
      options: map.approvalOptions(options),
      warning,
      escalation: map.escalation(request._meta),
    }),
  );
  const chosen = yield* decision;
  this.approvals.delete(id);
  reply.ok(
    chosen === null ? { outcome: { outcome: "cancelled" } } : { outcome: { outcome: "selected", optionId: chosen } },
  );
});

/// Publishes a question and answers the agent with `respond(answer)` once
/// the user has answered or dismissed it.
export const ask = Effect.fn("Acp.ask")(function* (
  this: AcpAgent,
  session: string,
  id: string,
  question: Omit<import("divergence/protocol").QuestionRequest, "event">,
  reply: RpcRequest["reply"],
  respond: (answer: QuestionAnswer) => unknown,
  toolCallId?: unknown,
) {
  const answered = Effect.callback<QuestionAnswer>((resume) => {
    this.questions.set(id, {
      session,
      requestId: reply.id,
      background: isBackground(this, session, { toolCallId }),
      resolve: (value) => resume(Effect.succeed(value)),
    });
    return Effect.sync(() => {
      this.questions.delete(id);
    });
  });
  this.emitFor(session, { event: "question", ...question });
  const answer = yield* answered;
  this.questions.delete(id);
  reply.ok(respond(answer));
});

export const onExtensionQuestion = Effect.fn("Acp.onExtensionQuestion")(function* (
  this: AcpAgent,
  dialect: import("./quirks.ts").Dialect,
  params: wire.Message,
  reply: RpcRequest["reply"],
) {
  const session = this.hostOf(String(params.sessionId ?? ""));
  const id = newId("acp-question");
  const asked = extensionQuestion(dialect, id, params);
  if (!asked) return reply.err(new RpcError(INVALID_PARAMS, "the question carried no answerable entries"));
  return yield* this.ask(session, id, asked.question, reply, (answer) => extensionAnswer(asked.shape, answer));
});

/// A plan the agent proposes. Both dialects wait for an answer, and
/// neither answer is the user's: the plan goes into the transcript and
/// the user replies in their own time.
/// The workspace a session's file requests resolve in.
export const onReadFile = Effect.fn("Acp.onReadFile")(function* (
  this: AcpAgent,
  request: wire.Message,
  reply: RpcRequest["reply"],
) {
  const path = yield* Effect.try({
    try: () => contain(this.workspaceOf(String(request.sessionId ?? "")), request.path),
    catch: (error) => new RpcError(RESOURCE_NOT_FOUND, errorMessage(error)),
  });
  const fs = yield* Fs;
  const read = yield* Effect.result(fs.read(path));
  if (Result.isFailure(read)) reply.err(new RpcError(RESOURCE_NOT_FOUND, `${request.path}: ${read.failure.message}`));
  else reply.ok({ content: sliceLines(read.success, request.line ?? undefined, request.limit ?? undefined) });
});

export const onWriteFile = Effect.fn("Acp.onWriteFile")(function* (
  this: AcpAgent,
  request: wire.Message,
  reply: RpcRequest["reply"],
) {
  const path = yield* Effect.try({
    try: () => contain(this.workspaceOf(String(request.sessionId ?? "")), request.path),
    catch: (error) => new RpcError(RESOURCE_NOT_FOUND, errorMessage(error)),
  });
  const fs = yield* Fs;
  // Parent creation and the write both report their actual failures.
  yield* fs.mkdir(parentOf(path), { recursive: true });
  const written = yield* Effect.result(fs.write(path, String(request.content ?? "")));
  if (Result.isFailure(written)) reply.err(new Error(`${request.path}: ${written.failure.message}`));
  else reply.ok({});
});

export const onTerminalCreate = Effect.fn("Acp.onTerminalCreate")(function* (
  this: AcpAgent,
  request: wire.Message,
  reply: RpcRequest["reply"],
) {
  const created = yield* Effect.result(
    this.terminals.create({ ...request, cwd: request.cwd ?? this.workspaceOf(String(request.sessionId)) }),
  );
  if (Result.isFailure(created)) reply.err(created.failure);
  else reply.ok({ terminalId: created.success });
});

export const onTerminalWait = Effect.fn("Acp.onTerminalWait")(function* (
  this: AcpAgent,
  request: wire.Message,
  reply: RpcRequest["reply"],
) {
  const waited = yield* Effect.result(this.terminals.wait(String(request.terminalId ?? "")));
  if (Result.isSuccess(waited)) {
    const exit = waited.success;
    this.refreshTerminal(String(request.terminalId ?? ""));
    reply.ok({ exitCode: exit.code, signal: exit.signal === null ? null : String(exit.signal) });
  } else reply.err(waited.failure);
});

export const onTerminalKill = Effect.fn("Acp.onTerminalKill")(function* (
  this: AcpAgent,
  request: wire.Message,
  reply: RpcRequest["reply"],
) {
  const killed = yield* Effect.result(this.terminals.kill(String(request.terminalId ?? "")));
  if (Result.isFailure(killed)) reply.err(killed.failure);
  else reply.ok({});
});

export const onTerminalRelease = Effect.fn("Acp.onTerminalRelease")(function* (
  this: AcpAgent,
  request: wire.Message,
  reply: RpcRequest["reply"],
) {
  const id = String(request.terminalId ?? "");
  this.refreshTerminal(id);
  yield* this.terminals.release(id);
  this.terminalTools.delete(id);
  reply.ok({});
});

// URL consent answers the request immediately; optional external completion is separate.
export const onElicitation = Effect.fn("Acp.onElicitation")(function* (
  this: AcpAgent,
  request: wire.Message,
  reply: RpcRequest["reply"],
) {
  const session = typeof request.sessionId === "string" ? this.hostOf(request.sessionId) : null;
  const message = String(request.message ?? "");
  if (request.mode === "url") {
    const url = String(request.url ?? "");
    const elicitation = request.elicitationId;
    if (typeof elicitation !== "string" || !/^https?:\/\//i.test(url)) return reply.ok({ action: "decline" });
    if (session === null) {
      yield* this.tell(
        `${this.name} asked to open ${url}. This request needs a confirmation outside a chat, which the app does not support yet.`,
        "warning",
      );
      return reply.ok({ action: "decline" });
    }
    const id = newId("acp-question");
    return yield* this.ask(
      session,
      id,
      {
        id,
        message,
        url,
        fields: [
          {
            id: "action",
            label: "Open this page?",
            kind: "select",
            options: [
              { value: "accept", label: "Open the page" },
              { value: "decline", label: "Decline" },
            ],
            allowOther: false,
            required: true,
          },
        ],
      },
      reply,
      (answer) => {
        const action = answer.cancelled ? "cancel" : answer.values?.action === "accept" ? "accept" : "decline";
        if (action === "accept")
          this.elicitations.set(elicitation, {
            session,
            background: session !== null && isBackground(this, session, { toolCallId: request.toolCallId }),
          });
        return { action };
      },
      request.toolCallId,
    );
  }
  if (request.mode !== undefined && request.mode !== null && request.mode !== "form")
    return reply.ok({ action: "decline" });
  if (session === null) {
    yield* this.tell(`${this.name} asked for input outside a chat: ${message}`, "warning");
    return reply.ok({ action: "decline" });
  }
  const id = newId("acp-question");
  return yield* this.ask(
    session,
    id,
    { id, message, fields: map.questionFields(request.requestedSchema) },
    reply,
    (answer) =>
      answer.cancelled
        ? { action: "cancel" }
        : { action: "accept", content: map.elicitationContent(request.requestedSchema, answer.values) },
    request.toolCallId,
  );
});

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.5latestNov 21, 2026>=5 <6134 KB6 permissionsListed
0.2.4Nov 16, 2026>=5 <6132.8 KB6 permissionsListed
0.2.3Nov 11, 2026>=5 <6108.9 KB6 permissionsListed
0.2.2Nov 9, 2026>=5 <6105.6 KB6 permissionsListed
0.2.1Oct 27, 2026>=2 <4105.3 KB6 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.