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.
Files
apps.test.ts10.4 KB
import { test } from "node:test";
import assert from "node:assert/strict";
import type { HostFeature, ToolContent } from "divergence/protocol";
import { embeddedApps } from "./apps.ts";
import { toolContent } from "./map.ts";
import { Recorder } from "./history.ts";
import { Replay } from "./replay.ts";
import { Session } from "./v2.ts";
import { harness, acpPeer, present, SESSION, update } from "./testing.ts";
import { settle } from "../sdk/testing.ts";
import type { Message } from "./wire.ts";
const html = "<!doctype html><html><body>Weather ☀</body></html>";
const ui = { csp: { resourceDomains: ["https://example.com"] }, prefersBorder: true };
const resource = { uri: "ui://weather/page", mimeType: "text/html;profile=mcp-app", text: html, _meta: { ui } };
const content = [
{ type: "content", content: { type: "text", text: "The forecast follows." } },
{ type: "content", content: { type: "resource", resource } },
{ type: "content", content: { type: "image", mimeType: "image/png", data: "aW1hZ2U=" } },
];
const result = {
content: [{ type: "text", text: "Sunny." }], structuredContent: { temperature: 20 },
_meta: { native: "retained" }, isError: false,
};
const app = { type: "mcp_app", server: "weather", tool: "forecast", resourceUri: resource.uri, html, meta: ui };
const fallback = toolContent(content);
const featureLists: (HostFeature[] | undefined)[] = [undefined, [], ["planCancelled"], ["mcpApps"]];
for (const version of [1, 2] as const) {
for (const hostFeatures of featureLists) {
test(`ACP v${version} gates embedded apps in live events and history for ${JSON.stringify(hostFeatures)}.`, async () => {
const enabled = hostFeatures?.includes("mcpApps") ?? false;
const updates: Message[] = [
{ sessionUpdate: version === 1 ? "tool_call" : "tool_call_update", toolCallId: "t", title: "Forecast", _meta: { mcp: { server: "weather", tool: "forecast" } } },
{ sessionUpdate: "tool_call_update", toolCallId: "t", content },
{ sessionUpdate: "tool_call_update", toolCallId: "t", status: "completed", rawOutput: result },
];
const replay = (params: Record<string, unknown>, _message: unknown, peer: { send: (value: unknown) => void }) => {
for (const value of updates)
peer.send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: params.sessionId, update: value } });
if (version === 2)
peer.send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: params.sessionId, update: { sessionUpdate: "replay_complete" } } });
return {};
};
const { agent, events, api, run } = harness("test", {
peer: acpPeer({
init: version === 1
? { agentCapabilities: { loadSession: true } }
: { protocolVersion: 2, info: { name: "peer", version: "2" }, capabilities: { session: {} } },
handlers: { "session/load": replay, "session/resume": replay, "session/list": () => ({ sessions: [] }) },
}),
});
const info = await run(present(agent.definition().initialize)(
{ agentId: agent.id, ...(hostFeatures === undefined ? {} : { hostFeatures }) },
{ agentId: agent.id, emit: () => {} },
));
assert.deepEqual(agent.hostFeatures, hostFeatures ?? []);
assert.equal(info.capabilities?.mcpApps, undefined);
assert.equal(agent.definition().mcp_read_resource, undefined);
assert.equal(agent.definition().mcp_call_tool, undefined);
const init = present(present(api.peers[0]).received.find((message) => message.method === "initialize"));
assert.deepEqual(init.params.capabilities, { elicitation: { form: {}, url: {} } });
assert.equal(JSON.stringify(init.params).includes("mcpApps"), false);
for (const value of updates) update(agent, value);
const live = events.filter((event) => event.event === "tool_call_started" || event.event === "tool_call_updated");
const lastContent = live.findLast((event) => event.content !== undefined)?.content;
const expected = enabled ? [{ ...app, result }, ...fallback] : fallback;
assert.deepEqual(lastContent, expected);
const history = await agent.readSession({ sessionId: SESSION, workspace: "/w" });
const item = history.items.find((item) => item.role === "tool");
assert.deepEqual(item?.role === "tool" ? item.call.content : undefined, expected);
// A result-only live patch after replay must retain the embedded page.
update(agent, { sessionUpdate: "tool_call_update", toolCallId: "t", status: "failed", rawOutput: { ...result, isError: true } });
await settle();
const latest = events.findLast((event) => event.event === "tool_call_updated");
if (enabled) assert.deepEqual(latest?.content, [{ ...app, result: { ...result, isError: true } }, ...fallback]);
await agent.closeSession({ sessionId: SESSION });
assert.equal(agent.embeddedTools.has(SESSION), false);
});
}
}
test("Embedded apps use explicit native identities and preserve fallback content.", () => {
for (const identity of [
{ _meta: { mcp: { server: "weather", tool: "forecast" } } },
{ _meta: { server: "weather", tool: "forecast" } },
{ rawInput: { server: "weather", tool: "forecast" } },
{ name: "mcp__weather__forecast" },
{ title: "mcp__weather__forecast" },
]) assert.deepEqual(embeddedApps({ ...identity, content }, fallback), [app, ...fallback]);
for (const identity of [{}, { name: "forecast" }, { title: "Running forecast" }, { _meta: { server: "weather" } }])
assert.deepEqual(embeddedApps({ ...identity, content }, fallback), fallback);
});
test("Embedded HTML accepts both MIME types and base64 UTF-8 without accepting unrelated resources.", () => {
const call = (resource: unknown) => ({ name: "mcp__weather__forecast", content: [{ type: "content", content: { type: "resource", resource } }] });
assert.deepEqual(embeddedApps(call({ ...resource, mimeType: "text/html" }), []), [app]);
assert.deepEqual(embeddedApps(call({ ...resource, text: undefined, blob: Buffer.from(html).toString("base64") }), []), [app]);
assert.deepEqual(embeddedApps(call({ ...resource, text: "", _meta: undefined }), []), [
{ type: "mcp_app", server: "weather", tool: "forecast", resourceUri: resource.uri, html: "" },
]);
for (const invalid of [
{ ...resource, uri: "https://example.com/page" },
{ ...resource, uri: "file:///page.html" },
{ ...resource, mimeType: "text/plain" },
{ ...resource, mimeType: undefined },
{ ...resource, text: undefined },
]) assert.deepEqual(embeddedApps(call(invalid), fallback), fallback);
assert.deepEqual(embeddedApps({ name: "mcp__weather__forecast", content: [{ type: "content", content: { type: "resource_link", uri: resource.uri } }] }, fallback), fallback);
});
test("Malformed embedded HTML is reported and keeps its fallback.", (t) => {
const warnings = t.mock.method(console, "warn", () => {});
for (const blob of ["not base64!", "/w=="])
assert.deepEqual(embeddedApps({ name: "mcp__weather__forecast", content: [{ type: "content", content: { type: "resource", resource: { ...resource, text: undefined, blob } } }] }, fallback), fallback);
assert.equal(warnings.mock.callCount(), 2);
assert.match(String(warnings.mock.calls[0].arguments[0]), /Cannot decode embedded MCP App ui:\/\/weather\/page/);
});
test("ACP results are attached only when native rawOutput exposes a completed MCP result.", () => {
for (const status of ["completed", "failed", "cancelled"])
assert.deepEqual(embeddedApps({ name: "mcp__weather__forecast", content, status, rawOutput: result }, fallback), [{ ...app, result }, ...fallback]);
for (const rawOutput of [undefined, "Sunny.", { text: "Sunny." }])
assert.deepEqual(embeddedApps({ name: "mcp__weather__forecast", content, status: "completed", rawOutput }, fallback), [app, ...fallback]);
assert.deepEqual(embeddedApps({ name: "mcp__weather__forecast", content, status: "in_progress", rawOutput: result }, fallback), [app, ...fallback]);
});
test("V1 retains partial call identity and replaces metadata and content in live and replay state.", () => {
const replay = new Recorder(true);
replay.push({ sessionUpdate: "tool_call", toolCallId: "t", content });
replay.push({ sessionUpdate: "tool_call_update", toolCallId: "t", _meta: { mcp: { server: "weather", tool: "forecast" } } });
const contents = () => {
const item = replay.finish()[0];
return item?.role === "tool" ? item.call.content : undefined;
};
assert.deepEqual(contents(), [app, ...fallback]);
replay.push({ sessionUpdate: "tool_call_update", toolCallId: "t", content: null, name: null });
assert.deepEqual(contents(), [app, ...fallback]);
replay.push({ sessionUpdate: "tool_call_update", toolCallId: "t", _meta: { unrelated: true } });
assert.deepEqual(contents(), fallback);
replay.push({ sessionUpdate: "tool_call_update", toolCallId: "t", name: "mcp__weather__forecast", content: [] });
assert.deepEqual(contents(), []);
});
test("V2 retains chunked apps and applies snapshot, metadata patch, and null clear semantics.", () => {
const session = new Session(true);
const push = (value: Message): ToolContent[] | undefined => {
session.push({ sessionUpdate: "tool_call_update", toolCallId: "t", ...value });
const item = session.items.get("tool:t");
return item?.role === "tool" ? item.call.content : undefined;
};
push({ _meta: { mcp: { server: "weather", tool: "forecast" } } });
for (const item of content) push({ sessionUpdate: "tool_call_content_chunk", content: item });
assert.deepEqual(push({ _meta: { unrelated: true } }), [app, ...fallback]);
assert.deepEqual(push({ status: "completed", rawOutput: result }), [{ ...app, result }, ...fallback]);
assert.deepEqual(push({ rawOutput: null }), [app, ...fallback]);
assert.deepEqual(push({ _meta: { mcp: null } }), fallback);
assert.deepEqual(push({ name: "mcp__weather__forecast" }), [app, ...fallback]);
assert.deepEqual(push({ name: null }), fallback);
assert.deepEqual(push({ content: null }), []);
});
test("Nested replay projections gate embedded pages independently in both ACP versions.", () => {
for (const version of [1, 2] as const) for (const enabled of [false, true]) {
const replay = new Replay("root", version, enabled);
replay.push({ sessionUpdate: version === 1 ? "tool_call" : "tool_call_update", toolCallId: "t", name: "mcp__weather__forecast", content }, "child");
const item = replay.finish("child")[0];
assert.deepEqual(item?.role === "tool" ? item.call.content : undefined, enabled ? [app, ...fallback] : fallback);
}
});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.