Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

13.1 KB
Raw Blame
/**
 * `penguin agent api …`, driven through `cli()` in-process against the fake server's agent API
 * and admin settings routes.
 *
 * - `keys create` prints the key bare on stdout and everything else on stderr; listing the keys
 *   afterwards names the new one by its prefix, never by the secret.
 * - `enable --open --approve read-only` sends one PUT turning the API on with keyless access and
 *   that approval mode, and prints the status it left; `disable` sends only the switch, so keyless
 *   access and the mode stay as they were.
 * - `set` sends only what it is given; given nothing, it sends nothing and fails.
 * - An unknown `--approve` mode fails before any request.
 * - The agent is never a default: without `--agent-id`, nothing is sent.
 * - `status` shows the server-wide switch to any member, an admin or not, from the agent's own
 *   settings read: the admin settings are never asked.
 * - `server off` / `server on` write the server-wide switch; any other state sends nothing.
 * - `keys rm` deletes the key; an unknown key fails with the server's code.
 * - The token file goes as Bearer on every request, a stored sign-in notwithstanding, wherever
 *   the server takes the token.
 * - A write the server refuses for the token (403 `human_required`) is retried once as the
 *   person's stored sign-in (`penguin auth login`), alone as the session cookie, and goes through.
 * - With no stored sign-in, each such write prints the sign-in hint, exits 1 and changes nothing.
 * - Inside a Session, or for a sign-in to another server, the stored sign-in is never sent: the
 *   write prints the hint and exits 1.
 * - A stored sign-in the server no longer accepts leaves the refusal: the hint, exit 1.
 */
import fs from "node:fs";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { writeSession } from "../src/auth-session.js";
import { cli } from "../src/index.js";
import { getMessages } from "../src/i18n.js";
import { FakeServer } from "./fake-server.js";

const t = getMessages("en");
const REF = "default_project/default_agent";
const API = "/api/projects/default_project/agents/default_agent/api";

let server: FakeServer;
let uninstall: () => void;
let stdout: string[];
let stderr: string[];
let restore: Array<{ mockRestore(): void }>;

beforeEach(() => {
  server = new FakeServer();
  uninstall = server.install();
  stdout = [];
  stderr = [];
  restore = [
    vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
      stdout.push(String(chunk));
      return true;
    }),
    vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
      stderr.push(String(chunk));
      return true;
    }),
  ];
});
afterEach(() => {
  for (const spy of restore) spy.mockRestore();
  uninstall();
});

const out = () => stdout.join("");
const err = () => stderr.join("");
/** The writes sent to the agent's API settings and to the admin settings, in order. */
const writes = () =>
  server.requests
    .filter((r) => r.method !== "GET")
    .map((r) => [r.method, r.path, r.body ?? null] as const);

describe("penguin agent api keys", () => {
  it("create prints the key bare on stdout and the rest on stderr", async () => {
    expect(
      await cli(["agent", "api", "keys", "create", "--agent-id", "default_agent", "--name", "ci"]),
    ).toBe(0);
    const [key] = server.agentApi.get(REF)!.keys;
    const [secret] = server.mintedSecrets;
    expect(out()).toBe(`${secret}\n`);
    expect(err()).toBe(`${t.agent.apiKeyCreated("ci", String(key!.prefix), REF)}\n`);
    expect(writes()).toEqual([["POST", `${API}/keys`, { name: "ci" }]]);

    stdout.length = 0;
    expect(await cli(["agent", "api", "keys", "ls", "--agent-id", "default_agent"])).toBe(0);
    expect(out()).toContain(`${String(key!.prefix)}…`);
    expect(out()).toContain(t.agent.apiKeyNever());
    expect(out()).not.toContain(secret!);
  });

  it("rm deletes the key; an unknown key fails with the server's code", async () => {
    await cli(["agent", "api", "keys", "create", "--agent-id", "default_agent", "--name", "ci"]);
    stdout.length = 0;
    expect(await cli(["agent", "api", "keys", "rm", "key1", "--agent-id", "default_agent"])).toBe(
      0,
    );
    expect(out()).toBe(`${t.agent.apiKeyDeleted("key1", REF)}\n`);
    expect(server.agentApi.get(REF)!.keys).toEqual([]);

    expect(await cli(["agent", "api", "keys", "rm", "key1", "--agent-id", "default_agent"])).toBe(
      1,
    );
    expect(err()).toContain("key_not_found");
  });

  it("ls says so when the agent has no keys", async () => {
    expect(await cli(["agent", "api", "keys", "ls", "--agent-id", "default_agent"])).toBe(0);
    expect(out()).toBe(`${t.agent.apiKeysEmpty(REF)}\n`);
  });
});

describe("penguin agent api enable / disable / set", () => {
  it("enable --open --approve read-only sends one PUT and prints the status it left", async () => {
    expect(
      await cli([
        "agent",
        "api",
        "enable",
        "--agent-id",
        "default_agent",
        "--open",
        "--approve",
        "read-only",
      ]),
    ).toBe(0);
    expect(writes()).toEqual([
      ["PUT", API, { enabled: true, open: true, approvalMode: "read-only" }],
    ]);
    const text = out();
    expect(text).toContain(t.agent.apiStatusTitle(REF));
    expect(text).toMatch(new RegExp(`${t.agent.apiFieldEnabled()}\\s+${t.agent.apiYes()}`));
    expect(text).toMatch(new RegExp(`${t.agent.apiFieldOpen()}\\s+${t.agent.apiYes()}`));
    expect(text).toMatch(new RegExp(`${t.agent.apiFieldApproval()}\\s+read-only`));
    expect(text).toContain("http://127.0.0.1:7399/api/amsp/v1");
    // Keyless access went on, so stderr carries the warning; stdout stays the status.
    expect(err()).toContain(t.agent.apiOpenWarning());
    expect(text).not.toContain(t.agent.apiOpenWarning());
  });

  it("disable sends only the switch: keyless access and the mode stay as they were", async () => {
    await cli(["agent", "api", "enable", "--agent-id", "default_agent", "--open"]);
    server.requests.length = 0;
    expect(await cli(["agent", "api", "disable", "--agent-id", "default_agent"])).toBe(0);
    expect(writes()).toEqual([["PUT", API, { enabled: false }]]);
    expect(server.agentApi.get(REF)).toMatchObject({ enabled: false, open: true });
  });

  it("set sends only what it is given; given nothing it sends nothing and fails", async () => {
    expect(await cli(["agent", "api", "set", "--agent-id", "default_agent", "--no-open"])).toBe(0);
    expect(writes()).toEqual([["PUT", API, { open: false }]]);
    expect(err()).not.toContain(t.agent.apiOpenWarning());

    server.requests.length = 0;
    expect(await cli(["agent", "api", "set", "--agent-id", "default_agent"])).toBe(1);
    expect(err()).toContain(t.agent.apiNothingToSet());
    expect(server.requests).toEqual([]);
  });

  it("an unknown approval mode fails before any request", async () => {
    const exit = vi.spyOn(process, "exit").mockImplementation(() => {
      throw new Error("exit");
    });
    try {
      expect(
        await cli(["agent", "api", "enable", "--agent-id", "default_agent", "--approve", "ask"]),
      ).toBe(1);
    } finally {
      exit.mockRestore();
    }
    expect(err()).toContain(t.approveModeInvalid("ask"));
    expect(server.requests).toEqual([]);
  });

  it("never picks the agent by default: without --agent-id nothing is sent", async () => {
    expect(await cli(["agent", "api", "enable"])).toBe(1);
    expect(server.requests).toEqual([]);
  });
});

describe("penguin agent api status / server", () => {
  it("status shows the server switch to a member who is not an admin, without asking the admin settings", async () => {
    server.adminSettings = { ...server.adminSettings, agentApiEnabled: false };
    server.adminForbidden = true;
    expect(await cli(["agent", "api", "status", "--agent-id", "default_agent"])).toBe(0);
    expect(out()).toMatch(new RegExp(`${t.agent.apiFieldServer()}\\s+off`));

    stdout.length = 0;
    expect(await cli(["agent", "api", "status", "--agent-id", "default_agent", "--json"])).toBe(0);
    expect(JSON.parse(out())).toEqual({
      agent: REF,
      baseUrl: "http://127.0.0.1:7399/api/amsp/v1",
      api: { enabled: false, open: false, approvalMode: "allow-all", keys: [] },
      serverEnabled: false,
    });
    expect(server.requests.some((r) => r.path === "/api/admin/settings")).toBe(false);
  });

  it("server off and on write the server-wide switch", async () => {
    expect(await cli(["agent", "api", "server", "off"])).toBe(0);
    expect(out()).toBe(`${t.agent.apiServerSet(false)}\n`);
    expect(await cli(["agent", "api", "server", "on", "--json"])).toBe(0);
    expect(writes()).toEqual([
      ["PUT", "/api/admin/settings", { agentApiEnabled: false }],
      ["PUT", "/api/admin/settings", { agentApiEnabled: true }],
    ]);
    expect(out()).toContain(`{"agentApiEnabled":true}`);
  });

  it("server with any other state sends nothing", async () => {
    expect(await cli(["agent", "api", "server", "maybe"])).toBe(1);
    expect(err()).toContain(t.agent.apiServerStateInvalid("maybe"));
    expect(server.requests).toEqual([]);
  });
});

describe("penguin agent api: the credential a request carries", () => {
  const BOOT_TOKEN = "boot-token-1";
  const LOGIN = "login-token-1";
  const asCookie = { cookie: `penguin_session=${LOGIN}` };
  const asBearer = { authorization: `Bearer ${BOOT_TOKEN}` };
  /** The token file the server writes at every boot, in the data root the fake pins. */
  const writeTokenFile = () =>
    fs.writeFileSync(path.join(process.env.ADELIE_HOME!, "api-token"), `${BOOT_TOKEN}\n`);
  /** `penguin auth login` against `target`: the stored sign-in, which the fake accepts. */
  const signIn = (target = "http://localhost:7399") => {
    writeSession(process.env.ADELIE_HOME!, { server: target, userId: "admin", token: LOGIN });
    server.logins.add(LOGIN);
  };
  const credentials = () => server.requests.map((r) => r.credential);
  const state = () => JSON.stringify([[...server.agentApi], server.adminSettings]);
  const WRITES = [
    [["enable", "--agent-id", "default_agent", "--open"]],
    [["disable", "--agent-id", "default_agent"]],
    [["set", "--agent-id", "default_agent", "--approve", "read-only"]],
    [["keys", "create", "--agent-id", "default_agent", "--name", "ci"]],
    [["keys", "rm", "key1", "--agent-id", "default_agent"]],
    [["server", "on"]],
  ];

  it("sends the token file as Bearer, a stored sign-in notwithstanding, wherever the server takes the token", async () => {
    writeTokenFile();
    signIn();
    for (const argv of [
      ["agent", "ls"],
      ["agent", "api", "status", "--agent-id", "default_agent"],
      ["agent", "api", "keys", "ls", "--agent-id", "default_agent"],
    ]) {
      expect(await cli(argv), argv.join(" ")).toBe(0);
    }
    expect(credentials()).toEqual([asBearer, asBearer, asBearer]);
  });

  it("retries a write refused human_required once as the stored sign-in, alone as the session cookie, and the write goes through", async () => {
    writeTokenFile();
    signIn();
    for (const argv of [
      ["agent", "api", "enable", "--agent-id", "default_agent", "--open"],
      ["agent", "api", "keys", "create", "--agent-id", "default_agent", "--name", "ci"],
      ["agent", "api", "keys", "rm", "key1", "--agent-id", "default_agent"],
      ["agent", "api", "server", "off"],
    ]) {
      expect(await cli(argv), argv.join(" ")).toBe(0);
    }
    expect(credentials()).toEqual([1, 2, 3, 4].flatMap(() => [asBearer, asCookie]));
    expect(server.agentApi.get(REF)).toMatchObject({ enabled: true, open: true, keys: [] });
    expect(server.adminSettings.agentApiEnabled).toBe(false);
  });

  it.each(WRITES)(
    "with no stored sign-in, %j prints the sign-in hint, exits 1 and changes nothing",
    async (argv) => {
      writeTokenFile();
      const before = state();
      expect(await cli(["agent", "api", ...argv])).toBe(1);
      expect(err()).toBe(`${t.agent.apiSignInRequired()}\n`);
      expect(out()).toBe("");
      expect(credentials()).toEqual([asBearer]);
      expect(state()).toBe(before);
    },
  );

  it.each([
    [
      "inside a Session",
      () => {
        process.env.ADELIE_SESSION_ID = "session-2026-10-09-10-00-00-5e55a001";
        signIn();
      },
    ],
    ["for a sign-in to another server", () => signIn("https://penguin.example")],
  ])(
    "%s, the stored sign-in is never sent: the write prints the hint and exits 1",
    async (_case, arrange) => {
      writeTokenFile();
      arrange();
      const before = state();
      expect(await cli(["agent", "api", "enable", "--agent-id", "default_agent", "--open"])).toBe(
        1,
      );
      expect(err()).toBe(`${t.agent.apiSignInRequired()}\n`);
      expect(credentials()).toEqual([asBearer]);
      expect(state()).toBe(before);
    },
  );

  it("a stored sign-in the server no longer accepts leaves the refusal: the hint, exit 1", async () => {
    writeTokenFile();
    signIn();
    server.logins.clear();
    const before = state();
    expect(await cli(["agent", "api", "enable", "--agent-id", "default_agent", "--open"])).toBe(1);
    expect(err()).toBe(`${t.agent.apiSignInRequired()}\n`);
    expect(credentials()).toEqual([asBearer, asCookie]);
    expect(state()).toBe(before);
  });
});