Skip to content

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

5.9 KB
Raw Blame
/**
 * Agent API management (`/api/projects/:projectId/agents/:agentId/api`): the API tab and
 * `penguin agent api` read and change one Agent's exposure here.
 *
 *   GET    /               member   the switch, keyless access, the approval mode, the keys
 *   PUT    /               owner    change the switch, keyless access and/or the approval mode
 *   POST   /keys           owner    create a key: the secret is in this response and nowhere else
 *   DELETE /keys/:keyId    owner    delete a key: its next request is refused
 *
 * Owner means the Project owner, the rule Agent deletion uses: exposing an Agent to programs
 * outside the Web App is a Project-level decision, and so is the approval mode those programs'
 * conversations start with. The settings live in this server's web.db (see AgentApi), never in
 * the Agent State the Agent itself can rewrite. And the writes take the owner's sign-in, never
 * the local API token every tool subprocess holds (403 `human_required`, see requireHuman): an
 * Agent must not switch on its own exposure from its shell. The reads stay open to the token,
 * for `penguin agent api status` and `keys ls`.
 */
import { Hono } from "hono";
import type { Context } from "hono";
import type {
  AgentApiKeyCreateResponse,
  AgentApiKeyInfo,
  AgentApiResponse,
} from "../../api/types.js";
import { requireHuman } from "../../auth/middleware.js";
import type { AppEnv } from "../../auth/middleware.js";
import { mintAgentApiKey } from "../../amsp/keys.js";
import { HttpError } from "../errors.js";
import {
  optionalBoolean,
  optionalEnum,
  readJson,
  requireString,
  requireValidId,
} from "../validate.js";
import { APPROVAL_MODES } from "./sessions.js";
import type { AgentApi, AgentApiKeyRow } from "../../mechanisms/agent-api.js";
import type { AgentConfig } from "../../mechanisms/agents.js";
import type { Access } from "../../mechanisms/projects.js";
import type { Settings } from "../../mechanisms/settings.js";

/** What this route group reaches — bound by its module (services/agent-routes.ts). */
export interface AgentApiRouteDeps {
  agentApi: AgentApi;
  agentConfigService: Pick<AgentConfig, "requireExists">;
  access: Pick<Access, "requireProjectAccess" | "requireProjectOwner">;
  settings: Pick<Settings, "getAgentApiEnabled">;
  now: () => Date;
}

/** A key as the list shows it: never the secret, never its hash. */
function keyInfo(row: AgentApiKeyRow): AgentApiKeyInfo {
  return {
    keyId: row.keyId,
    name: row.name,
    prefix: row.prefix,
    createdBy: row.createdBy,
    createdAt: row.createdAt,
    lastUsedAt: row.lastUsedAt,
  };
}

export function agentApiRoutes(deps: AgentApiRouteDeps): Hono<AppEnv> {
  const app = new Hono<AppEnv>();

  /** The Agent's settings as the tab reads them; a never-configured Agent reads as off, keyed, allow-all. */
  const settings = (projectId: string, agentId: string): AgentApiResponse => {
    const row = deps.agentApi.get(projectId, agentId);
    return {
      api: {
        enabled: row?.enabled ?? false,
        open: row?.open ?? false,
        approvalMode: row?.approvalMode ?? "allow-all",
        keys: deps.agentApi.listKeys(projectId, agentId).map(keyInfo),
      },
      // The tab says when the admin has the whole API off: only an admin can read that setting.
      serverEnabled: deps.settings.getAgentApiEnabled(),
    };
  };

  /** The path's Agent, once the caller may reach it (`owner` for the writes) and it exists. */
  const agentOf = async (
    c: Context<AppEnv>,
    owner: boolean,
  ): Promise<{ projectId: string; agentId: string }> => {
    const projectId = requireValidId(c, "projectId");
    const agentId = requireValidId(c, "agentId");
    if (owner) deps.access.requireProjectOwner(c.var.user.userId, projectId);
    else deps.access.requireProjectAccess(c.var.user.userId, projectId);
    await deps.agentConfigService.requireExists(projectId, agentId);
    return { projectId, agentId };
  };

  app.get("/", async (c) => {
    const { projectId, agentId } = await agentOf(c, false);
    return c.json(settings(projectId, agentId));
  });

  app.put("/", async (c) => {
    requireHuman(c);
    const { projectId, agentId } = await agentOf(c, true);
    const body = await readJson(c);
    // Every field is checked before any is written.
    const enabled = optionalBoolean(body, "enabled");
    const open = optionalBoolean(body, "open");
    const approvalMode = optionalEnum(body, "approvalMode", APPROVAL_MODES);
    deps.agentApi.set(
      projectId,
      agentId,
      {
        ...(enabled !== undefined ? { enabled } : {}),
        ...(open !== undefined ? { open } : {}),
        ...(approvalMode !== undefined ? { approvalMode } : {}),
      },
      deps.now().toISOString(),
    );
    return c.json(settings(projectId, agentId));
  });

  app.post("/keys", async (c) => {
    requireHuman(c);
    const { projectId, agentId } = await agentOf(c, true);
    const body = await readJson(c);
    const name = requireString(body, "name", { maxLen: 64, label: "name" }).trim();
    if (name === "") throw new HttpError(400, "bad_request", "name must be 1-64 characters.");
    const minted = mintAgentApiKey();
    const row: AgentApiKeyRow = {
      keyId: minted.keyId,
      projectId,
      agentId,
      prefix: minted.prefix,
      name,
      createdBy: c.var.user.userId,
      createdAt: deps.now().toISOString(),
      lastUsedAt: null,
    };
    deps.agentApi.insertKey({ ...row, tokenHash: minted.tokenHash });
    return c.json(
      { key: keyInfo(row), secret: minted.secret } satisfies AgentApiKeyCreateResponse,
      201,
    );
  });

  app.delete("/keys/:keyId", async (c) => {
    requireHuman(c);
    const { projectId, agentId } = await agentOf(c, true);
    if (!deps.agentApi.deleteKey(projectId, agentId, c.req.param("keyId"))) {
      throw new HttpError(404, "key_not_found", "This Agent has no key with that id.");
    }
    return c.body(null, 204);
  });

  return app;
}