Skip to content

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

14.1 KB
Raw Blame
/**
 * `penguin agent` — list and create agents through the server, and manage an agent's public API.
 *
 *   penguin agent ls [--project-id <id>] [--json] [--server <url>]
 *   penguin agent create --agent-id <id> [--name <s>] [--description <s>]
 *                        [--plugins <a,b>] [--project-id <id>] [--json] [--server <url>]
 *   penguin agent api status  --agent-id <id> [--project-id <id>] [--json] [--server <url>]
 *   penguin agent api enable  --agent-id <id> [--open | --no-open] [--approve <mode>] …
 *   penguin agent api disable --agent-id <id> …
 *   penguin agent api set     --agent-id <id> [--open | --no-open] [--approve <mode>] …
 *   penguin agent api keys ls     --agent-id <id> …
 *   penguin agent api keys create --agent-id <id> --name <s> …
 *   penguin agent api keys rm <keyId> --agent-id <id> …
 *   penguin agent api server on|off [--json] [--server <url>]
 *
 * `create` mirrors the Web dialog's fields: id (required), display name, description,
 * and library plugins to seed (comma-separated names; unknown names are rejected by the
 * server before anything is created).
 *
 * `api` is the Agent page's API tab over /api/projects/:p/agents/:a/api: whether external
 * programs may talk to the agent, keyless access, the approval mode API conversations are
 * created with (`--approve`, validated as `run` and `chat` validate theirs), and the keys. The
 * agent is always named with `--agent-id` — exposing one is never left to a default. `enable`,
 * `disable` and `set` print the resulting status, as `status` does; its last line is the
 * server-wide switch, which the settings read reports to any member and which `server on|off`
 * (admins only) writes. `keys
 * create` prints the key bare on stdout — the only time it exists anywhere — and everything else
 * on stderr, so `KEY=$(penguin agent api keys create …)` captures exactly the key.
 *
 * The writes (`enable`, `disable`, `set`, `keys create`, `keys rm`, `server`) take a person's
 * sign-in: the server refuses the local API token on them with 403 `human_required`, so that
 * an Agent cannot expose itself from its own shell. Outside a Session the client then retries
 * once as the stored `penguin auth login` (client.ts); when that is missing or refused too, the
 * write prints what to run instead.
 * Docs: /docs/cli § "penguin agent".
 */
import type { Command } from "commander";
import type {
  AgentApiKeyCreateResponse,
  AgentApiResponse,
  AgentApiSettings,
  AgentApiUpdateRequest,
  AgentCreateResponse,
  AgentSummary,
  ServerSettingsResponse,
} from "@adelie/server/api";
import { resolveApprovalMode } from "../approval.js";
import { ApiError, resolveConnection, resolveProjectId, ServerClient } from "../client.js";
import { listAgents } from "../server-session.js";
import { displayWidth, renderTable } from "../table.js";
import type { Messages } from "../i18n.js";

const enc = encodeURIComponent;

interface ApiOpts {
  agentId: string;
  projectId?: string;
  json?: boolean;
  server?: string;
  open?: boolean;
  approve?: string;
  name?: string;
}

async function connect(opts: { server?: string }, t: Messages): Promise<ServerClient> {
  return new ServerClient(await resolveConnection({ server: opts.server }, t), t);
}

/** The agent's API, as the server names it: project and agent ids, and the routes under it. */
function target(opts: ApiOpts): { projectId: string; agentId: string; ref: string; path: string } {
  const projectId = resolveProjectId(opts.projectId);
  const agentId = String(opts.agentId).trim();
  return {
    projectId,
    agentId,
    ref: `${projectId}/${agentId}`,
    path: `/api/projects/${enc(projectId)}/agents/${enc(agentId)}/api`,
  };
}

/** What `--open` / `--no-open` / `--approve` ask to change; an invalid mode exits before any request. */
function settingsPatch(opts: ApiOpts, t: Messages): AgentApiUpdateRequest {
  return {
    ...(typeof opts.open === "boolean" ? { open: opts.open } : {}),
    ...(opts.approve !== undefined ? { approvalMode: resolveApprovalMode(opts.approve, t) } : {}),
  };
}

/** Prints the settings as `status` shows them: a heading and one aligned line per fact, or JSON. */
function printStatus(
  client: ServerClient,
  ref: string,
  res: AgentApiResponse,
  json: boolean,
  t: Messages,
): void {
  const baseUrl = `${client.conn.baseUrl}/api/amsp/v1`;
  const settings: AgentApiSettings = res.api;
  const server = res.serverEnabled;
  if (json) {
    process.stdout.write(
      `${JSON.stringify({ agent: ref, baseUrl, api: settings, serverEnabled: server })}\n`,
    );
    return;
  }
  const yesNo = (on: boolean) => (on ? t.agent.apiYes() : t.agent.apiNo());
  const rows: Array<[string, string]> = [
    [t.agent.apiFieldEnabled(), yesNo(settings.enabled)],
    [t.agent.apiFieldOpen(), yesNo(settings.open)],
    [t.agent.apiFieldApproval(), settings.approvalMode],
    [t.agent.apiFieldBaseUrl(), baseUrl],
    [t.agent.apiFieldAgentId(), ref],
    [t.agent.apiFieldKeys(), String(settings.keys.length)],
    [t.agent.apiFieldServer(), server ? t.agent.apiServerOn() : t.agent.apiServerOff()],
  ];
  const width = Math.max(...rows.map(([label]) => displayWidth(label)));
  const lines = rows.map(
    ([label, value]) => `  ${label}${" ".repeat(width - displayWidth(label))}  ${value}`,
  );
  process.stdout.write(`${t.agent.apiStatusTitle(ref)}\n${lines.join("\n")}\n`);
}

/**
 * A write that changes who can reach an agent. The server's 403 `human_required` that is left
 * after the client's retry as a stored sign-in — the request carried the local API token, and no
 * sign-in the server accepts stood in for it — becomes the line saying what to run.
 */
async function exposureWrite<T>(
  client: ServerClient,
  method: string,
  apiPath: string,
  body: unknown,
  t: Messages,
): Promise<T> {
  try {
    return await client.request<T>(method, apiPath, body);
  } catch (err) {
    if (err instanceof ApiError && err.code === "human_required") {
      throw new Error(t.agent.apiSignInRequired());
    }
    throw err;
  }
}

/** One PUT of the agent's API settings, then the status it left. */
async function writeSettings(opts: ApiOpts, patch: AgentApiUpdateRequest, t: Messages) {
  const { path, ref } = target(opts);
  const client = await connect(opts, t);
  const res = await exposureWrite<AgentApiResponse>(client, "PUT", path, patch, t);
  printStatus(client, ref, res, opts.json === true, t);
  // The Web App asks before keyless access goes on; a terminal has no dialog, so it warns on
  // stderr once the switch is on (stdout stays the status or the JSON).
  if (patch.open === true && res.api.open) process.stderr.write(`${t.agent.apiOpenWarning()}\n`);
}

function registerApiCommands(agent: Command, t: Messages): void {
  const api = agent.command("api").description(t.agent.apiDesc);
  /** The options every command naming an agent takes. */
  const forAgent = (cmd: Command): Command =>
    cmd
      .requiredOption("--agent-id <id>", t.common.agentId)
      .option("--project-id <id>", t.common.projectId)
      .option("--json", t.common.json)
      .option("--server <url>", t.common.server);
  /** `--open` / `--no-open` / `--approve`: neither switch given leaves `open` undefined. */
  const settingsOptions = (cmd: Command): Command =>
    cmd
      .option("--open", t.agent.apiOpen)
      .option("--no-open", t.agent.apiNoOpen)
      .option("--approve <mode>", t.agent.apiApprove);

  forAgent(api.command("status").description(t.agent.apiStatusDesc)).action(
    async (opts: ApiOpts) => {
      const { path, ref } = target(opts);
      const client = await connect(opts, t);
      const res = await client.request<AgentApiResponse>("GET", path);
      printStatus(client, ref, res, opts.json === true, t);
    },
  );

  settingsOptions(forAgent(api.command("enable").description(t.agent.apiEnableDesc))).action(
    async (opts: ApiOpts) => {
      await writeSettings(opts, { enabled: true, ...settingsPatch(opts, t) }, t);
    },
  );

  forAgent(api.command("disable").description(t.agent.apiDisableDesc)).action(
    async (opts: ApiOpts) => {
      await writeSettings(opts, { enabled: false }, t);
    },
  );

  settingsOptions(forAgent(api.command("set").description(t.agent.apiSetDesc))).action(
    async (opts: ApiOpts) => {
      const patch = settingsPatch(opts, t);
      if (Object.keys(patch).length === 0) {
        process.stderr.write(`${t.agent.apiNothingToSet()}\n`);
        process.exitCode = 1;
        return;
      }
      await writeSettings(opts, patch, t);
    },
  );

  const keys = api.command("keys").description(t.agent.apiKeysDesc);

  forAgent(keys.command("ls").description(t.agent.apiKeysLsDesc)).action(async (opts: ApiOpts) => {
    const { path, ref } = target(opts);
    const client = await connect(opts, t);
    const res = await client.request<AgentApiResponse>("GET", path);
    if (opts.json === true) {
      process.stdout.write(`${JSON.stringify(res.api.keys)}\n`);
      return;
    }
    if (res.api.keys.length === 0) {
      process.stdout.write(`${t.agent.apiKeysEmpty(ref)}\n`);
      return;
    }
    process.stdout.write(
      renderTable(
        [
          t.agent.apiColKeyId(),
          t.agent.apiColKeyName(),
          t.agent.apiColPrefix(),
          t.agent.apiColCreated(),
          t.agent.apiColLastUsed(),
        ],
        res.api.keys.map((k) => [
          k.keyId,
          k.name,
          `${k.prefix}…`,
          k.createdAt,
          k.lastUsedAt ?? t.agent.apiKeyNever(),
        ]),
      ),
    );
  });

  forAgent(keys.command("create").description(t.agent.apiKeysCreateDesc))
    .requiredOption("--name <name>", t.agent.apiKeyName)
    .action(async (opts: ApiOpts) => {
      const { path, ref } = target(opts);
      const client = await connect(opts, t);
      const res = await exposureWrite<AgentApiKeyCreateResponse>(
        client,
        "POST",
        `${path}/keys`,
        { name: String(opts.name) },
        t,
      );
      if (opts.json === true) {
        process.stdout.write(`${JSON.stringify(res)}\n`);
        return;
      }
      process.stdout.write(`${res.secret}\n`);
      process.stderr.write(`${t.agent.apiKeyCreated(res.key.name, res.key.prefix, ref)}\n`);
    });

  forAgent(keys.command("rm <keyId>").description(t.agent.apiKeysRmDesc)).action(
    async (keyId: string, opts: ApiOpts) => {
      const { path, ref } = target(opts);
      const client = await connect(opts, t);
      await exposureWrite<void>(client, "DELETE", `${path}/keys/${enc(keyId)}`, undefined, t);
      if (opts.json === true) {
        process.stdout.write(`${JSON.stringify({ deleted: keyId })}\n`);
        return;
      }
      process.stdout.write(`${t.agent.apiKeyDeleted(keyId, ref)}\n`);
    },
  );

  api
    .command("server <state>")
    .description(t.agent.apiServerDesc)
    .option("--json", t.common.json)
    .option("--server <url>", t.common.server)
    .action(async (state: string, opts: { json?: boolean; server?: string }) => {
      const wanted = state.trim().toLowerCase();
      if (wanted !== "on" && wanted !== "off") {
        process.stderr.write(`${t.agent.apiServerStateInvalid(state)}\n`);
        process.exitCode = 1;
        return;
      }
      const client = await connect(opts, t);
      const res = await exposureWrite<ServerSettingsResponse>(
        client,
        "PUT",
        "/api/admin/settings",
        { agentApiEnabled: wanted === "on" },
        t,
      );
      const on = res.settings.agentApiEnabled;
      if (opts.json === true) {
        process.stdout.write(`${JSON.stringify({ agentApiEnabled: on })}\n`);
        return;
      }
      process.stdout.write(`${t.agent.apiServerSet(on)}\n`);
    });
}

export function registerAgentCommand(program: Command, t: Messages): void {
  const agent = program.command("agent").description(t.agent.desc);

  agent
    .command("ls")
    .description(t.agent.lsDesc)
    .option("--project-id <id>", t.common.projectId)
    .option("--json", t.common.json)
    .option("--server <url>", t.common.server)
    .action(async (opts) => {
      const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
      const projectId = resolveProjectId(opts.projectId);
      const agents = await listAgents(client, projectId);
      if (opts.json === true) {
        process.stdout.write(`${JSON.stringify(agents)}\n`);
        return;
      }
      process.stdout.write(
        renderTable(
          [t.agent.colId(), t.agent.colName(), t.agent.colSessions(), t.agent.colDescription()],
          agents.map((a: AgentSummary) => [
            a.agentId,
            a.name ?? "",
            String(a.sessionCount),
            (a.description ?? "").slice(0, 60),
          ]),
        ),
      );
    });

  agent
    .command("create")
    .description(t.agent.createDesc)
    .requiredOption("--agent-id <id>", t.agent.createId)
    .option("--name <name>", t.agent.createName)
    .option("--description <text>", t.agent.createDescription)
    .option("--plugins <names>", t.agent.createPlugins)
    .option("--project-id <id>", t.common.projectId)
    .option("--json", t.common.json)
    .option("--server <url>", t.common.server)
    .action(async (opts) => {
      const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
      const projectId = resolveProjectId(opts.projectId);
      const plugins =
        typeof opts.plugins === "string"
          ? opts.plugins
              .split(",")
              .map((s: string) => s.trim())
              .filter((s: string) => s.length > 0)
          : undefined;
      const res = await client.request<AgentCreateResponse>(
        "POST",
        `/api/projects/${encodeURIComponent(projectId)}/agents`,
        {
          agentId: String(opts.agentId),
          ...(opts.name !== undefined ? { name: String(opts.name) } : {}),
          ...(opts.description !== undefined ? { description: String(opts.description) } : {}),
          ...(plugins !== undefined && plugins.length > 0 ? { plugins } : {}),
        },
      );
      if (opts.json === true) {
        process.stdout.write(`${JSON.stringify(res.agent)}\n`);
        return;
      }
      process.stdout.write(`${t.agent.created(res.agent.agentId, projectId)}\n`);
    });

  registerApiCommands(agent, t);
}