A local-first multi-agent app development platform, built on PenguinHarness
/**
* 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;
}