Skip to content

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

3.1 KB
Raw Blame
/**
 * The Agent API mechanism: what a node may require of the per-Agent API settings and keys,
 * declared apart from what implements it (db/repos/agent-api.ts).
 *
 * This server's own state, kept in web.db: never in the Agent State (the Agent must not be able
 * to expose itself or loosen the approvals its API conversations run with) and never in the
 * Project file (synchronized across machines in company mode, while exposure is one server's).
 */
import { Interface } from "@adelie/core/kernel";
import type { ApprovalMode } from "../api/types.js";

/** One Agent's API settings row. */
export interface AgentApiRow {
  projectId: string;
  agentId: string;
  /** The API tab's switch: off = every /api/amsp request for the Agent is 404 `agent_not_found`. */
  enabled: boolean;
  /** Keyless access: a request without `Authorization` is accepted; off = 401 `unauthorized`. */
  open: boolean;
  /** The approval mode an API Session is created with (copied onto its row, never read per decision). */
  approvalMode: ApprovalMode;
  updatedAt: string;
}

/** One API key as stored, minus its hash: what the list shows and what authentication resolves to. */
export interface AgentApiKeyRow {
  keyId: string;
  projectId: string;
  agentId: string;
  /** The key's first 16 characters (`penguin_` + 8). */
  prefix: string;
  name: string;
  /** user_id of whoever created it. */
  createdBy: string;
  createdAt: string;
  /** Stamped once per run request that authenticated with it; null = never used. */
  lastUsedAt: string | null;
}

/** The fields a settings write may change; omitted ones keep their stored value. */
export interface AgentApiPatch {
  enabled?: boolean;
  open?: boolean;
  approvalMode?: ApprovalMode;
}

/** AgentApi: the mechanism AgentApiRepo implements. */
@Interface()
export abstract class AgentApi {
  /** The Agent's row; null = never configured, which reads as disabled, keyed, allow-all. */
  abstract get(projectId: string, agentId: string): AgentApiRow | null;
  /** Writes the patch over the stored row (or the defaults) and returns the row as stored. */
  abstract set(projectId: string, agentId: string, patch: AgentApiPatch, at: string): AgentApiRow;
  /** The Project's Agents whose switch is on, in one query (the Agent list's `apiEnabled`). */
  abstract enabledAgents(projectId: string): string[];
  /** The Agent's keys, oldest first. */
  abstract listKeys(projectId: string, agentId: string): AgentApiKeyRow[];
  abstract insertKey(row: AgentApiKeyRow & { tokenHash: string }): void;
  /** The key whose secret hashes to `tokenHash`; null when none does. */
  abstract findKeyByHash(tokenHash: string): AgentApiKeyRow | null;
  abstract touchKey(keyId: string, at: string): void;
  /** Hard delete; false when the Agent has no such key. */
  abstract deleteKey(projectId: string, agentId: string, keyId: string): boolean;
  /** Drops the Agent's settings and keys (the Agent was deleted). */
  abstract deleteByAgent(projectId: string, agentId: string): void;
  /** Drops every settings row and key of the Project (the Project was deleted). */
  abstract deleteByProject(projectId: string): void;
}