A local-first multi-agent app development platform, built on PenguinHarness
/**
* An Agent's public API in the Web App: the Agent page's API tab (features/agents/api-tab.tsx),
* the Agents list's mark (agents-page.tsx) and the admin's server-wide switch
* (features/settings/agent-api-section.tsx). The views render to static markup and the
* confirmations are driven through their handlers against the fetch fake (node env, no DOM).
*
* - An Agent whose API is off shows the switch alone: no approval mode, no address, no keys, no
* examples.
* - Enabled, the tab shows the approval mode select on the stored mode, the Base URL and the
* Agent ID each with its copy button, and every key by its prefix with when it was created and
* last used (or that it never was).
* - A created key's secret is on screen in its own panel, whose copy button copies exactly the
* secret and whose Done hands back; with no secret pending there is no panel.
* - The examples call the real Base URL and Agent ID, with the key left as $ADELIE_AGENT_KEY.
* - With the admin's server-wide switch off, the tab's switch is disabled and says why, to every
* member and not only an admin (the tab's own read carries the switch); a member who is not the
* owner finds every control disabled, no key actions, and is told why.
* - The three writes that ask nothing first draw a refused reason under the control that asked:
* the API switch, the approval select and the keyless switch — one alert each, in its own place,
* and none at all when nothing was refused.
* - Turning the API off asks first, in the danger tone. Answered yes, it writes the switch off
* and hands on what the server stored; a failed write is handed on as the failure.
* - Deleting a key asks first, naming it. Answered yes, it deletes that key and hands on its id;
* a refused delete hands the server's words on, so the card that asked can keep them.
* - The Agents list carries the plug mark, named for screen readers, only on an Agent whose API
* is on.
* - Turning the Agent API off server-wide asks first, in the danger tone; answered yes, it writes
* the switch off and hands on what the server stored — without closing the card itself, and a
* refusal it asked for is drawn inside that card while its buttons wait for the write.
* - The owner's tab ends with Try it, its input holding the example question; a member's tab has
* no Try it.
* - With the admin's server-wide switch off, Try it's input and Run are disabled, and Run carries
* the reason.
*/
import { beforeEach, describe, expect, it, vi } from "vitest";
import { createElement, isValidElement } from "react";
import type { ReactElement, ReactNode } from "react";
import { renderToStaticMarkup } from "react-dom/server";
import type { AgentApiKeyInfo, AgentApiResponse, AgentApiSettings } from "@adelie/server/api";
import { Button, CopyButton, Select, ToggleRow } from "@adelie/ui";
import {
AgentApiOffConfirm,
KeylessOnConfirm,
ApiTabView,
DeleteKeyConfirm,
OneTimeKey,
agentApiBaseUrl,
agentApiExamples,
} from "../src/features/agents/api-tab";
import type { ApiTabViewProps } from "../src/features/agents/api-tab";
import { AgentApiMark } from "../src/features/agents/agents-page";
import { AgentApiServerOffConfirm } from "../src/features/settings/agent-api-section";
import { S } from "../src/lib/strings";
import { apiError, json, stubFetch } from "./helpers/fetch";
const toasts = vi.hoisted(() => [] as string[]);
vi.mock("@adelie/ui", async (importOriginal) => {
const actual = await importOriginal<typeof import("@adelie/ui")>();
return {
...actual,
toastSuccess: (text: string) => toasts.push(`success: ${text}`),
toastError: (text: string) => toasts.push(`error: ${text}`),
};
});
const USED: AgentApiKeyInfo = {
keyId: "kq3VtX9cRb2LmN0a",
name: "docs-site search",
prefix: "penguin_Zr8kQ2vT",
createdBy: "admin",
createdAt: "2026-10-01T08:00:00.000Z",
lastUsedAt: "2026-10-07T09:30:00.000Z",
};
const FRESH: AgentApiKeyInfo = {
...USED,
keyId: "Hc7pW2sYd4EfJ6uB",
name: "weekly report",
prefix: "penguin_4mGxL7pA",
lastUsedAt: null,
};
const ON: AgentApiSettings = {
enabled: true,
open: false,
approvalMode: "read-only",
keys: [USED, FRESH],
};
const BASE = agentApiBaseUrl("http://127.0.0.1:7369");
/** Obviously fake and short: no key-shaped literal lives in the tests. */
const SECRET = "penguin_fake-secret";
const noop = () => {};
function props(over: Partial<ApiTabViewProps> = {}): ApiTabViewProps {
return {
projectId: "demo",
agentId: "coder",
settings: ON,
serverEnabled: true,
isOwner: true,
busy: false,
baseUrl: BASE,
agentRef: "demo/coder",
draftName: null,
secret: null,
onToggleEnabled: noop,
onApprovalMode: noop,
onToggleOpen: noop,
onStartKey: noop,
onDraftName: noop,
onCreateKey: noop,
onCancelKey: noop,
onSecretDone: noop,
onDeleteKey: noop,
...over,
};
}
const render = (over: Partial<ApiTabViewProps> = {}) =>
renderToStaticMarkup(createElement(ApiTabView, props(over)));
/** The props a ConfirmModal element was given. */
type Confirm = ReactElement<{
open: boolean;
tone?: string;
title: string;
confirmLabel: string;
children: ReactNode;
onConfirm: () => void;
/** True while the card's write is in flight: both buttons are then disabled. */
busy?: boolean;
/** The server's words for a write the card asked for and it refused (confirm-modal's slot). */
refusal?: string;
}>;
/** Every element of `type` in a tree of plain elements, its children followed. */
function find(node: ReactNode, type: unknown): ReactElement<Record<string, unknown>>[] {
return ([] as ReactNode[])
.concat(node)
.filter(isValidElement)
.flatMap((el) => {
const element = el as ReactElement<{ children?: ReactNode }>;
const own = element.type === type ? [element as ReactElement<Record<string, unknown>>] : [];
return [...own, ...find(element.props.children, type)];
});
}
beforeEach(() => {
toasts.length = 0;
});
describe("the API tab", () => {
it("shows the switch alone while the API is off", () => {
const html = render({ settings: { ...ON, enabled: false } });
expect(html).toContain(`aria-label="${S.agent.apiEnable}"`);
expect(html).not.toContain(S.agent.apiApprovalMode);
expect(html).not.toContain(BASE);
expect(html).not.toContain(USED.prefix);
expect(html).not.toContain("ADELIE_AGENT_KEY");
});
it("shows the approval mode, the address with copy buttons and every key by its prefix once on", () => {
const html = render();
expect(html).toContain(S.agent.apiApprovalMode);
expect(html).toContain(S.chat.approvalModeNames["read-only"]);
expect(html).toContain(BASE);
expect(html).toContain(`aria-label="${S.agent.apiCopy(S.agent.apiBaseUrl)}"`);
expect(html).toContain("demo/coder");
expect(html).toContain(`aria-label="${S.agent.apiCopy(S.agent.apiAgentId)}"`);
expect(html.split('data-testid="api-key"').length - 1).toBe(2);
expect(html).toContain(`${USED.prefix}…`);
expect(html).toContain(`${FRESH.prefix}…`);
expect(html).toContain(S.agent.apiKeyNever);
});
it("puts a created key's secret in its own panel, whose copy button copies exactly it", () => {
expect(render({ secret: SECRET })).toContain(SECRET);
expect(find(ApiTabView(props()), OneTimeKey)).toEqual([]);
const onDone = vi.fn();
const panel = OneTimeKey({ secret: SECRET, onDone });
const [copy] = find(panel, CopyButton);
expect(copy!.props.text).toBe(SECRET);
const [done] = find(panel, Button);
(done!.props.onClick as () => void)();
expect(onDone).toHaveBeenCalledOnce();
});
it("calls the real Base URL and Agent ID in its examples, the key left to the environment", () => {
const { curl, sdk } = agentApiExamples(BASE, "demo/coder");
expect(curl).toContain(`curl -N ${BASE}/agents/demo/coder/runs`);
expect(curl).toContain("Bearer $ADELIE_AGENT_KEY");
expect(sdk).toContain(`baseUrl: "${BASE}"`);
expect(sdk).toContain(`agent: "demo/coder"`);
expect(sdk).toContain("process.env.ADELIE_AGENT_KEY");
expect(render()).toContain(`${BASE}/agents/demo/coder/runs`);
});
it("disables the switch and tells any member why when the admin has the API off server-wide", () => {
const [toggle] = find(ApiTabView(props({ serverEnabled: false })), ToggleRow);
expect(toggle!.props.disabled).toBe(true);
expect(render({ serverEnabled: false })).toContain(S.agent.apiAdminOff);
expect(render({ serverEnabled: false, isOwner: false })).toContain(S.agent.apiAdminOff);
expect(render()).not.toContain(S.agent.apiAdminOff);
});
it("ends the owner's tab with Try it, its input holding the example; a member's tab has none", () => {
const html = render();
expect(html.indexOf(S.agent.apiTry)).toBeGreaterThan(html.indexOf(S.agent.apiExamples));
expect(html).toContain(`value="${S.agent.apiTryExample}"`);
expect(render({ isOwner: false })).not.toContain(S.agent.apiTry);
expect(render({ settings: { ...ON, enabled: false } })).not.toContain(S.agent.apiTry);
});
it("disables Try it's input and Run when the admin has the API off, Run saying why", () => {
const html = render({ serverEnabled: false });
const section = html.slice(html.indexOf(S.agent.apiTry));
expect(section).toMatch(/<input[^>]*disabled=""/);
// The section's first button is Run.
const run = /<button[^>]*>[^<]*<\/button>/.exec(section)?.[0] ?? "";
expect(run).toContain(S.agent.apiTryRun);
expect(run).toContain('disabled=""');
expect(run).toContain(`data-tooltip="${S.agent.apiAdminOff}"`);
const enabled = render().slice(render().indexOf(S.agent.apiTry));
expect(enabled).not.toMatch(/<input[^>]*disabled=""/);
});
it("draws each refused write's reason under the control that asked, and no alert when none was refused", () => {
// Nothing refused: the tab has no alert at all — the sentences appear only when asked for.
expect(render()).not.toContain('role="alert"');
const enable = S.agent.apiEnableRefused("write refused");
const mode = S.agent.apiApprovalModeRefused(
S.chat.approvalModeNames["always-ask"] as string,
"write refused",
);
const keyless = S.agent.apiKeylessOffRefused("write refused");
const html = render({
enableRefusal: enable,
approvalRefusal: mode,
keylessOffRefusal: keyless,
});
expect(html.split('role="alert"').length - 1).toBe(3);
// Each one sits under its own control: the switch, the approval select, the keyless switch.
expect(html.indexOf(enable)).toBeLessThan(html.indexOf(S.agent.apiApprovalMode));
expect(html.indexOf(mode)).toBeGreaterThan(html.indexOf(S.agent.apiApprovalMode));
expect(html.indexOf(keyless)).toBeGreaterThan(html.indexOf(S.agent.apiOpenHint));
});
it("leaves a member who is not the owner every control disabled and no key action", () => {
const tree = ApiTabView(props({ isOwner: false }));
const toggles = find(tree, ToggleRow);
expect(toggles).toHaveLength(2);
expect(toggles.every((t) => t.props.disabled === true)).toBe(true);
expect(find(tree, Select)[0]!.props.disabled).toBe(true);
const html = render({ isOwner: false });
expect(html).toContain(S.agent.apiOwnerOnly);
expect(html).not.toContain(S.agent.apiNewKey);
expect(html).not.toContain(`aria-label="${S.agent.apiDeleteKey} ${USED.name}"`);
expect(render()).toContain(`aria-label="${S.agent.apiDeleteKey} ${USED.name}"`);
});
});
describe("turning an Agent's API off", () => {
const confirm = (onSettled: (o: unknown) => void, onWriting = noop, onClose = noop) =>
AgentApiOffConfirm({
open: true,
projectId: "demo",
agentId: "coder",
onClose,
onWriting,
onSettled,
busy: false,
}) as Confirm;
it("asks first in the danger tone; answered yes, writes it off and hands on what was stored", async () => {
const stored: AgentApiResponse = { api: { ...ON, enabled: false }, serverEnabled: true };
const fetch = stubFetch(() => json(stored));
const onWriting = vi.fn();
const onSettled = vi.fn();
const question = confirm(onSettled, onWriting);
expect(question.props.tone).toBeUndefined();
expect(question.props.title).toBe(S.agent.apiOffTitle);
expect(fetch.requests).toEqual([]);
question.props.onConfirm();
expect(onWriting).toHaveBeenCalledOnce();
await vi.waitFor(() => expect(onSettled).toHaveBeenCalledExactlyOnceWith(stored));
expect(fetch.requests.map((r) => [r.method, r.path, r.body])).toEqual([
["PUT", "/api/projects/demo/agents/coder/api", { enabled: false }],
]);
});
it("hands on a failed write as the failure", async () => {
stubFetch(() => apiError(403, "forbidden"));
const onSettled = vi.fn();
confirm(onSettled).props.onConfirm();
await vi.waitFor(() => expect(onSettled).toHaveBeenCalledOnce());
expect(onSettled.mock.calls[0]![0]).toHaveProperty("error");
});
it("leaves the card open: answering yes writes without closing it first", async () => {
stubFetch(() => apiError(403, "forbidden"));
const onClose = vi.fn();
const onSettled = vi.fn();
confirm(onSettled, noop, onClose).props.onConfirm();
await vi.waitFor(() => expect(onSettled).toHaveBeenCalledOnce());
// The page closes this card on the landing of the write, and keeps it on a refusal.
expect(onClose).not.toHaveBeenCalled();
});
});
describe("allowing keyless access", () => {
const confirm = (onSettled: (o: unknown) => void, onWriting = noop, onClose = noop) =>
KeylessOnConfirm({
open: true,
projectId: "demo",
agentId: "coder",
onClose,
onWriting,
onSettled,
busy: false,
}) as Confirm;
it("warns first in the danger tone; answered yes, writes it on and hands on what was stored", async () => {
const stored: AgentApiResponse = { api: { ...ON, open: true }, serverEnabled: true };
const fetch = stubFetch(() => json(stored));
const onWriting = vi.fn();
const onSettled = vi.fn();
const question = confirm(onSettled, onWriting);
expect(question.props.tone).toBeUndefined();
expect(question.props.title).toBe(S.agent.apiOpenTitle);
expect(fetch.requests).toEqual([]);
question.props.onConfirm();
expect(onWriting).toHaveBeenCalledOnce();
await vi.waitFor(() => expect(onSettled).toHaveBeenCalledExactlyOnceWith(stored));
expect(fetch.requests.map((r) => [r.method, r.path, r.body])).toEqual([
["PUT", "/api/projects/demo/agents/coder/api", { open: true }],
]);
});
it("hands on a failed write as the failure", async () => {
stubFetch(() => apiError(403, "forbidden"));
const onSettled = vi.fn();
confirm(onSettled).props.onConfirm();
await vi.waitFor(() => expect(onSettled).toHaveBeenCalledOnce());
expect(onSettled.mock.calls[0]![0]).toHaveProperty("error");
});
it("leaves the card open: answering yes writes without closing it first", async () => {
stubFetch(() => apiError(403, "forbidden"));
const onClose = vi.fn();
const onSettled = vi.fn();
confirm(onSettled, noop, onClose).props.onConfirm();
await vi.waitFor(() => expect(onSettled).toHaveBeenCalledOnce());
expect(onClose).not.toHaveBeenCalled();
});
});
describe("deleting a key", () => {
const confirm = (handlers: {
onDeleted: (id: string) => void;
onRefused: (why: string) => void;
}) =>
DeleteKeyConfirm({
record: USED,
projectId: "demo",
agentId: "coder",
onClose: noop,
onWriting: noop,
onDeleted: handlers.onDeleted,
onRefused: handlers.onRefused,
busy: false,
}) as Confirm;
it("asks first, naming the key; answered yes, deletes it and hands on its id", async () => {
const fetch = stubFetch(() => new Response(null, { status: 204 }));
const onDeleted = vi.fn();
const question = confirm({ onDeleted, onRefused: vi.fn() });
expect(question.props.open).toBe(true);
expect(question.props.tone).toBeUndefined();
expect(renderToStaticMarkup(question.props.children as ReactElement)).toContain(
S.agent.apiDeleteKeyBody(USED.name),
);
expect(fetch.requests).toEqual([]);
question.props.onConfirm();
await vi.waitFor(() => expect(onDeleted).toHaveBeenCalledExactlyOnceWith(USED.keyId));
expect(fetch.requests.map((r) => `${r.method} ${r.path}`)).toEqual([
`DELETE /api/projects/demo/agents/coder/api/keys/${USED.keyId}`,
]);
});
it("hands a refused delete's reason on, for the card to keep, and hands on no id", async () => {
stubFetch(() => apiError(404, "key_not_found", "No such key."));
const onDeleted = vi.fn();
const onRefused = vi.fn();
const onClose = vi.fn();
(
DeleteKeyConfirm({
record: USED,
projectId: "demo",
agentId: "coder",
onClose,
onWriting: noop,
onDeleted,
onRefused,
busy: false,
}) as Confirm
).props.onConfirm();
await vi.waitFor(() => expect(onRefused).toHaveBeenCalledOnce());
// A refused delete leaves the card (and the key it named) where it was.
expect(onClose).not.toHaveBeenCalled();
// The server's own words, which the card wraps in S.common.refused — not a toast that leaves.
expect(onRefused.mock.calls[0]![0]).toContain("No such key.");
expect(onDeleted).not.toHaveBeenCalled();
expect(toasts).toEqual([]);
});
it("draws a refusal the page hands back inside the card, beside the button that retries it", () => {
const question = DeleteKeyConfirm({
record: USED,
projectId: "demo",
agentId: "coder",
onClose: noop,
onWriting: noop,
onDeleted: noop,
onRefused: noop,
busy: false,
refusal: S.common.refused("No such key."),
}) as Confirm;
expect(question.props.refusal).toBe(S.common.refused("No such key."));
});
});
describe("the Agents list", () => {
it("marks an Agent whose API is on with the plug, named for screen readers, and no other", () => {
const on = renderToStaticMarkup(createElement(AgentApiMark, { enabled: true }));
expect(on).toContain(`data-tooltip="${S.agent.apiOn}"`);
expect(on).toContain(`<span class="sr-only">${S.agent.apiOn}</span>`);
expect(renderToStaticMarkup(createElement(AgentApiMark, { enabled: false }))).toBe("");
});
});
describe("the server-wide switch", () => {
it("asks first in the danger tone; answered yes, writes it off and hands on what was stored", async () => {
const fetch = stubFetch(() => json({ settings: { agentApiEnabled: false } }));
const onSettled = vi.fn();
const onClose = vi.fn();
const question = AgentApiServerOffConfirm({
open: true,
onClose,
onWriting: noop,
onSettled,
busy: false,
}) as Confirm;
expect(question.props.tone).toBeUndefined();
expect(fetch.requests).toEqual([]);
question.props.onConfirm();
await vi.waitFor(() => expect(onSettled).toHaveBeenCalledExactlyOnceWith({ enabled: false }));
// Whether the card closes is the page's call, made once the outcome is known — not the
// card's own move on the way out of the request.
expect(onClose).not.toHaveBeenCalled();
expect(fetch.requests.map((r) => [r.method, r.path, r.body])).toEqual([
["PUT", "/api/admin/settings", { agentApiEnabled: false }],
]);
});
it("draws a refusal inside the card, and greys its buttons while the write is in flight", () => {
const base = { open: true, onClose: noop, onWriting: noop, onSettled: noop };
const refused = AgentApiServerOffConfirm({
...base,
busy: false,
refusal: S.common.refused("admin settings are read-only"),
}) as Confirm;
expect(refused.props.refusal).toBe(S.common.refused("admin settings are read-only"));
expect(refused.props.busy).toBe(false);
const inFlight = AgentApiServerOffConfirm({ ...base, busy: true }) as Confirm;
expect(inFlight.props.busy).toBe(true);
// Nothing refused yet: the slot is absent rather than empty, so it is simply not drawn.
expect(inFlight.props.refusal).toBeUndefined();
});
});