Skip to content

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

8.6 KB
Raw Blame
/**
 * Agent routes:
 * GET|POST /api/projects/:p/agents, DELETE /:agentId (owner only), and
 * GET /api/projects/:p/agent-deletions/:deletionId (owner only), how far a delete's background
 * removal has got.
 * The list is the union of DB entries and directory scan results, including active
 * Session count, total Session count, config last-modified time, and whether the Agent's API
 * switch is on.
 */
import { Hono } from "hono";
import type {
  AgentCreateResponse,
  AgentDeleteResponse,
  AgentDeletionInfo,
  AgentDeletionResponse,
  AgentsResponse,
  AgentSummary,
} from "../../api/types.js";
import type { AppEnv } from "../../auth/middleware.js";
import { HttpError } from "../errors.js";
import { settleWithin } from "../settle.js";
import {
  badRequest,
  optionalString,
  optionalStringArray,
  readJson,
  requireProjectDir,
  requireString,
  requireValidId,
} from "../validate.js";
import { readArchiveBase64 } from "./agent-transfer.js";
import type { SessionManager } from "../../runtime/session-manager.js";
import type { SessionService } from "../../services/session-service.js";
import type { AgentConfig, AgentLifecycle } from "../../mechanisms/agents.js";
import type { TraceIndex } from "../../mechanisms/traces.js";
import type { ErrorLog } from "../../mechanisms/observability.js";
import type { Schedules, SessionIndex } from "../../mechanisms/sessions.js";
import type { Access } from "../../mechanisms/projects.js";
import type { AgentApi } from "../../mechanisms/agent-api.js";
import { refuseBuiltinDeletion } from "../../services/agent-service.js";

/** What this route group reaches — bound by its module (src/modules). */
export interface AgentsRouteDeps {
  agentApi: AgentApi;
  agentConfigService: AgentConfig;
  agentService: AgentLifecycle;
  errorsRepo: ErrorLog;
  manager: SessionManager;
  access: Access;
  schedulesRepo: Schedules;
  sessionService: SessionService;
  sessionsRepo: SessionIndex;
  traceIndex: TraceIndex;
}

/** Window size in days for the card's activity sparkline (last 30 days, including today). */
const ACTIVITY_DAYS = 30;

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

  app.get("/", async (c) => {
    // Defensive id validation: don't rely on the implicit invariant that requireProjectAccess always runs before path construction.
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    const items = await deps.agentService.listAgents(projectId);
    // One query for the whole list: which Agents have their API switch on (this server's web.db).
    const apiEnabled = new Set(deps.agentApi.enabledAgents(projectId));
    const agents: AgentSummary[] = await Promise.all(
      items.map(async (item) => {
        const stats = await deps.sessionService.sessionStats(
          projectId,
          item.agentId,
          ACTIVITY_DAYS,
        );
        return {
          ...item,
          activeSessionCount: deps.manager.activeCountForAgent(projectId, item.agentId),
          sessionCount: stats.sessionCount,
          sessionActivity: stats.activity,
          apiEnabled: apiEnabled.has(item.agentId),
        };
      }),
    );
    return c.json({ agents } satisfies AgentsResponse);
  });

  app.post("/", async (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    const body = await readJson(c);
    const agentId = requireString(body, "agentId", { label: "agentId" });
    const name = optionalString(body, "name", { minLen: 1, maxLen: 100, label: "name" });
    const description = optionalString(body, "description", {
      maxLen: 2000,
      label: "description",
    });
    // Library plugins to seed the new Agent with (the create dialog's picker); unknown names
    // are rejected before the Agent directory exists.
    const plugins = optionalStringArray(body, "plugins");
    // Skills imported from a directory the user picked. The pair only means anything together, so
    // half of it is a bad request rather than a silently ignored field.
    const skillsDirectory = optionalString(body, "skillsDirectory", {
      minLen: 1,
      maxLen: 4096,
      label: "skillsDirectory",
    });
    const directorySkills = optionalStringArray(body, "directorySkills");
    let directory: { path: string; names: string[] } | undefined;
    if (skillsDirectory !== undefined || directorySkills !== undefined) {
      if (skillsDirectory === undefined || directorySkills === undefined) {
        throw badRequest("skillsDirectory and directorySkills must be sent together.");
      }
      // The same admission the discovery route applies, so the two entry points cannot disagree
      // on what a valid directory is: a relative path would otherwise resolve against the server
      // process's cwd instead of being rejected.
      directory = { path: await requireProjectDir(skillsDirectory), names: directorySkills };
    }
    // Optional snapshot seed: the new Agent starts from an exported package instead of the
    // default template (the service rejects combining it with seeding).
    const archive = body.dataBase64 === undefined ? undefined : readArchiveBase64(body);
    const item = await deps.agentService.createAgent(
      projectId,
      agentId,
      name,
      description,
      plugins,
      directory,
      archive,
    );
    const agent: AgentSummary = {
      ...item,
      activeSessionCount: 0,
      sessionCount: 0,
      sessionActivity: Array.from({ length: ACTIVITY_DAYS }, () => 0),
      // A new Agent's API is off until its owner turns it on.
      apiEnabled: false,
    };
    return c.json({ agent } satisfies AgentCreateResponse, 201);
  });

  app.delete("/:agentId", async (c) => {
    const projectId = requireValidId(c, "projectId");
    const agentId = requireValidId(c, "agentId");
    // Deletion is a Project-level management operation: owner only.
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    await deps.agentConfigService.requireExists(projectId, agentId);
    // Refused before any run is touched.
    refuseBuiltinDeletion(agentId);
    // Mark as deleting and converge active runs (beginAgentDeletion): any new Task during
    // this window gets 409, preventing the race where a new task recreates the directory
    // and revives the Agent between abort and the move. Abort cleanup writes the Trace
    // asynchronously; wait for it to finish before moving the directory, and clear the
    // deleting flag once the move is done (success or failure).
    const runnings = deps.manager.beginAgentDeletion(projectId, agentId);
    let deletion: AgentDeletionInfo;
    try {
      await settleWithin(runnings, 5000);
      // One rename takes the folder out of every list and route; its contents are removed in
      // the background, which the answer reports and GET /agent-deletions/:id follows.
      deletion = await deps.agentService.deleteAgent(projectId, agentId);
      deps.sessionsRepo.deleteByAgent(projectId, agentId);
      // Trace-index rows describe files that just left: drop them with the Agent.
      deps.traceIndex.removeAgent(projectId, agentId);
      // Per-Agent runtime state keyed on the now-removed sessions/agent: drop it so nothing is
      // orphaned (session ids are never reused, so a leftover row is dead weight). Usage records
      // are deliberately kept — historical stats survive Agent deletion (see deleteAgent).
      deps.schedulesRepo.deleteByAgent(projectId, agentId);
      deps.errorsRepo.deleteByAgent(projectId, agentId);
      // The Agent's API exposure goes with it: a later Agent created under the same id starts
      // off, and no key minted for this one opens it.
      deps.agentApi.deleteByAgent(projectId, agentId);
    } finally {
      deps.manager.endAgentDeletion(projectId, agentId);
    }
    return c.json({ deletion } satisfies AgentDeleteResponse, 202);
  });

  return app;
}

/** GET /api/projects/:projectId/agent-deletions/:deletionId: where a delete's removal stands. */
export function agentDeletionsRoutes(
  deps: Pick<AgentsRouteDeps, "access" | "agentService">,
): Hono<AppEnv> {
  const app = new Hono<AppEnv>();

  app.get("/:deletionId", (c) => {
    const projectId = requireValidId(c, "projectId");
    const deletionId = requireValidId(c, "deletionId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const deletion = deps.agentService.agentDeletion(projectId, deletionId);
    if (deletion === null) {
      throw new HttpError(404, "agent_deletion_not_found", "No such deletion is in progress.");
    }
    return c.json({ deletion } satisfies AgentDeletionResponse);
  });

  return app;
}