Add built-in agent routes and gate

Co-Authored-By: Paperclip <noreply@paperclip.ing>

server/src/__tests__/built-in-agent-routes.test.ts

@@ -0,0 +1,241 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const companyId = "22222222-2222-4222-8222-222222222222";
+const agentId = "11111111-1111-4111-8111-111111111111";
+
+const mockAccessService = vi.hoisted(() => ({
+  decide: vi.fn(),
+}));
+
+const mockBuiltInAgentService = vi.hoisted(() => ({
+  list: vi.fn(),
+  ensure: vi.fn(),
+  reset: vi.fn(),
+}));
+
+const mockLogActivity = vi.hoisted(() => vi.fn());
+
+function allowDecision() {
+  return {
+    allowed: true,
+    action: "agents:create",
+    reason: "allow_explicit_grant",
+    explanation: "Allowed.",
+  };
+}
+
+function denyDecision() {
+  return {
+    allowed: false,
+    action: "agents:create",
+    reason: "deny_missing_grant",
+    explanation: "Missing permission: agents:create.",
+  };
+}
+
+function builtInState(overrides: Record<string, unknown> = {}) {
+  return {
+    definition: {
+      key: "briefs",
+      displayName: "Briefs Agent",
+      featureKeys: ["briefs"],
+      shortPurpose: "Prepares concise operational briefs.",
+      defaultInstructions: "Write briefs.",
+      defaultRole: "general",
+      allowedAdapterTypes: ["codex_local"],
+    },
+    status: "ready",
+    agentId,
+    agent: {
+      id: agentId,
+      companyId,
+      name: "Briefs Agent",
+      role: "general",
+      status: "idle",
+      adapterType: "codex_local",
+      adapterConfig: { model: "gpt-5.4" },
+    },
+    pauseReason: null,
+    ...overrides,
+  };
+}
+
+function registerModuleMocks() {
+  vi.doMock("../services/index.js", () => ({
+    accessService: () => mockAccessService,
+    logActivity: mockLogActivity,
+  }));
+  vi.doMock("../services/built-in-agents.js", () => ({
+    builtInAgentService: () => mockBuiltInAgentService,
+  }));
+}
+
+async function createApp(actor: Record<string, unknown>) {
+  const [{ builtInAgentRoutes }, { errorHandler }] = await Promise.all([
+    vi.importActual<typeof import("../routes/built-in-agents.js")>("../routes/built-in-agents.js"),
+    vi.importActual<typeof import("../middleware/index.js")>("../middleware/index.js"),
+  ]);
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = actor;
+    next();
+  });
+  app.use("/api", builtInAgentRoutes({} as any));
+  app.use(errorHandler);
+  return app;
+}
+
+describe("built-in agent routes", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    registerModuleMocks();
+    vi.clearAllMocks();
+    mockAccessService.decide.mockResolvedValue(allowDecision());
+    mockBuiltInAgentService.list.mockResolvedValue([builtInState()]);
+    mockBuiltInAgentService.ensure.mockResolvedValue(builtInState());
+    mockBuiltInAgentService.reset.mockResolvedValue(builtInState());
+  });
+
+  it("lists built-in agent state for actors with company access", async () => {
+    const app = await createApp({
+      type: "board",
+      userId: "board-user",
+      companyIds: [companyId],
+      source: "session",
+      isInstanceAdmin: false,
+    });
+
+    const res = await request(app).get(`/api/companies/${companyId}/built-in-agents`);
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockBuiltInAgentService.list).toHaveBeenCalledWith(companyId);
+    expect(res.body).toEqual([expect.objectContaining({ status: "ready", agentId })]);
+  });
+
+  it("denies list requests outside the actor company boundary", async () => {
+    const app = await createApp({
+      type: "board",
+      userId: "board-user",
+      companyIds: ["33333333-3333-4333-8333-333333333333"],
+      source: "session",
+      isInstanceAdmin: false,
+    });
+
+    const res = await request(app).get(`/api/companies/${companyId}/built-in-agents`);
+
+    expect(res.status, JSON.stringify(res.body)).toBe(403);
+    expect(mockBuiltInAgentService.list).not.toHaveBeenCalled();
+  });
+
+  it("provisions through the agents:create gate and passes optional adapter overrides", async () => {
+    const app = await createApp({
+      type: "board",
+      userId: "board-user",
+      companyIds: [companyId],
+      source: "session",
+      isInstanceAdmin: false,
+    });
+
+    const res = await request(app)
+      .post(`/api/companies/${companyId}/built-in-agents/briefs/provision`)
+      .send({ adapterType: "codex_local", adapterConfig: { model: "gpt-5.4" } });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockAccessService.decide).toHaveBeenCalledWith({
+      actor: expect.objectContaining({ type: "board" }),
+      action: "agents:create",
+      resource: { type: "company", companyId },
+    });
+    expect(mockBuiltInAgentService.ensure).toHaveBeenCalledWith(companyId, "briefs", {
+      adapterType: "codex_local",
+      adapterConfig: { model: "gpt-5.4" },
+    });
+    expect(mockLogActivity).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
+      companyId,
+      actorType: "user",
+      actorId: "board-user",
+      action: "built_in_agent.provision_requested",
+      entityId: agentId,
+    }));
+  });
+
+  it("denies provision when agents:create is not allowed", async () => {
+    mockAccessService.decide.mockResolvedValue(denyDecision());
+    const app = await createApp({
+      type: "board",
+      userId: "board-user",
+      companyIds: [companyId],
+      source: "session",
+      isInstanceAdmin: false,
+    });
+
+    const res = await request(app)
+      .post(`/api/companies/${companyId}/built-in-agents/briefs/provision`)
+      .send({ adapterType: "codex_local" });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(403);
+    expect(res.body.details).toMatchObject({ reason: "deny_missing_grant" });
+    expect(mockBuiltInAgentService.ensure).not.toHaveBeenCalled();
+  });
+
+  it("rejects provision bodies with unknown fields", async () => {
+    const app = await createApp({
+      type: "board",
+      userId: "board-user",
+      companyIds: [companyId],
+      source: "session",
+      isInstanceAdmin: false,
+    });
+
+    const res = await request(app)
+      .post(`/api/companies/${companyId}/built-in-agents/briefs/provision`)
+      .send({ adapterType: "codex_local", unexpected: true });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(400);
+    expect(mockBuiltInAgentService.ensure).not.toHaveBeenCalled();
+  });
+
+  it("resets registry defaults through the same agents:create gate", async () => {
+    const app = await createApp({
+      type: "agent",
+      agentId: "manager-agent",
+      companyId,
+      source: "agent_key",
+    });
+
+    const res = await request(app)
+      .post(`/api/companies/${companyId}/built-in-agents/briefs/reset`)
+      .send({});
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockBuiltInAgentService.reset).toHaveBeenCalledWith(companyId, "briefs");
+    expect(mockLogActivity).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
+      companyId,
+      actorType: "agent",
+      actorId: "manager-agent",
+      agentId: "manager-agent",
+      action: "built_in_agent.reset",
+      entityId: agentId,
+    }));
+  });
+
+  it("denies agent actors from provisioning across company boundaries", async () => {
+    const app = await createApp({
+      type: "agent",
+      agentId: "manager-agent",
+      companyId: "33333333-3333-4333-8333-333333333333",
+      source: "agent_key",
+    });
+
+    const res = await request(app)
+      .post(`/api/companies/${companyId}/built-in-agents/briefs/reset`)
+      .send({});
+
+    expect(res.status, JSON.stringify(res.body)).toBe(403);
+    expect(mockAccessService.decide).not.toHaveBeenCalled();
+    expect(mockBuiltInAgentService.reset).not.toHaveBeenCalled();
+  });
+});

server/src/__tests__/built-in-agents.test.ts

@@ -132,6 +132,22 @@ describeEmbeddedPostgres("built-in agents", () => {
     expect(rows).toHaveLength(1);
   });
 
+  it("rejects adapter types outside the built-in definition allowlist", async () => {
+    const companyId = await seedCompany();
+
+    await expect(builtInAgentService(db).ensure(companyId, "briefs", {
+      adapterType: "http",
+      adapterConfig: { url: "https://example.test/webhook" },
+    })).rejects.toMatchObject({
+      status: 422,
+      details: {
+        code: "built_in_agent_adapter_not_allowed",
+        key: "briefs",
+        allowedAdapterTypes: ["codex_local", "claude_local", "gemini_local", "opencode_local", "process"],
+      },
+    });
+  });
+
   it("recovers an orphaned marked row instead of creating a duplicate", async () => {
     const companyId = await seedCompany();
     const orphanId = randomUUID();
@@ -180,6 +196,83 @@ describeEmbeddedPostgres("built-in agents", () => {
     });
   });
 
+  it("requires configured built-ins with typed precondition failures and paused warnings", async () => {
+    const companyId = await seedCompany();
+    const builtIns = builtInAgentService(db);
+
+    await expect(builtIns.requireBuiltInAgent(companyId, "briefs")).rejects.toMatchObject({
+      status: 412,
+      details: {
+        code: "built_in_agent_not_configured",
+        key: "briefs",
+        status: "not_provisioned",
+        agentId: null,
+      },
+    });
+
+    const needsSetup = await builtIns.ensure(companyId, "briefs");
+    await expect(builtIns.requireBuiltInAgent(companyId, "briefs")).rejects.toMatchObject({
+      status: 412,
+      details: {
+        code: "built_in_agent_not_configured",
+        key: "briefs",
+        status: "needs_setup",
+        agentId: needsSetup.agentId,
+      },
+    });
+
+    const ready = await builtIns.ensure(companyId, "briefs", {
+      adapterType: "codex_local",
+      adapterConfig: { model: "gpt-5.4" },
+    });
+    await expect(builtIns.requireBuiltInAgent(companyId, "briefs")).resolves.toMatchObject({
+      agent: { id: ready.agentId },
+      warning: null,
+    });
+
+    await agentService(db).pause(ready.agentId!, "maintenance");
+    await expect(builtIns.requireBuiltInAgent(companyId, "briefs")).resolves.toMatchObject({
+      agent: { id: ready.agentId },
+      warning: {
+        code: "built_in_agent_paused",
+        key: "briefs",
+        agentId: ready.agentId,
+        pauseReason: "maintenance",
+      },
+    });
+  });
+
+  it("resets marked agents back to registry display defaults without replacing adapter setup", async () => {
+    const companyId = await seedCompany();
+    const builtIns = builtInAgentService(db);
+    const ready = await builtIns.ensure(companyId, "briefs", {
+      adapterType: "codex_local",
+      adapterConfig: { model: "gpt-5.4" },
+    });
+
+    await agentService(db).update(ready.agentId!, {
+      name: "Custom Briefs",
+      role: "engineer",
+      title: "Custom",
+      capabilities: "Custom purpose",
+    });
+
+    const reset = await builtIns.reset(companyId, "briefs");
+
+    expect(reset).toMatchObject({
+      status: "ready",
+      agentId: ready.agentId,
+      agent: {
+        name: "Briefs Agent",
+        role: "general",
+        title: null,
+        capabilities: "Prepares concise operational briefs for the board and agent company.",
+        adapterType: "codex_local",
+        adapterConfig: { model: "gpt-5.4" },
+      },
+    });
+  });
+
   it("blocks deleting a built-in agent", async () => {
     const companyId = await seedCompany();
     const state = await builtInAgentService(db).ensure(companyId, "briefs");

server/src/app.ts

@@ -14,6 +14,7 @@ import { applyTrustProxy, parseTrustProxyEnv } from "./middleware/trust-proxy.js
 import { healthRoutes } from "./routes/health.js";
 import { companyRoutes } from "./routes/companies.js";
 import { companySkillRoutes } from "./routes/company-skills.js";
+import { builtInAgentRoutes } from "./routes/built-in-agents.js";
 import { teamsCatalogRoutes } from "./routes/teams-catalog.js";
 import { agentRoutes } from "./routes/agents.js";
 import { projectRoutes } from "./routes/projects.js";
@@ -226,6 +227,7 @@ export async function createApp(
   api.use("/companies", companyRoutes(db, opts.storageService));
   api.use(llmRoutes(db));
   api.use(companySkillRoutes(db));
+  api.use(builtInAgentRoutes(db));
   api.use(teamsCatalogRoutes(db));
   api.use(agentRoutes(db, { pluginWorkerManager: workerManager }));
   api.use(assetRoutes(db, opts.storageService));

server/src/routes/built-in-agents.ts

@@ -0,0 +1,95 @@
+import { Router, type Request } from "express";
+import type { Db } from "@paperclipai/db";
+import { builtInAgentProvisionSchema } from "@paperclipai/shared";
+import { validate } from "../middleware/validate.js";
+import { forbidden } from "../errors.js";
+import { accessService, logActivity } from "../services/index.js";
+import { builtInAgentService } from "../services/built-in-agents.js";
+import { authorizationDeniedDetails } from "../services/authorization.js";
+import { assertCompanyAccess, getActorInfo } from "./authz.js";
+
+export function builtInAgentRoutes(db: Db) {
+  const router = Router();
+  const access = accessService(db);
+  const svc = builtInAgentService(db);
+
+  async function assertCanProvisionBuiltInAgents(req: Request, companyId: string) {
+    assertCompanyAccess(req, companyId);
+    const decision = await access.decide({
+      actor: req.actor,
+      action: "agents:create",
+      resource: { type: "company", companyId },
+    });
+    if (decision.allowed) return;
+    throw forbidden(decision.explanation, authorizationDeniedDetails(decision));
+  }
+
+  async function logBuiltInAgentMutation(
+    req: Request,
+    input: {
+      companyId: string;
+      action: "built_in_agent.provision_requested" | "built_in_agent.reset";
+      key: string;
+      agentId: string | null;
+      status: string;
+    },
+  ) {
+    const actor = getActorInfo(req);
+    await logActivity(db, {
+      companyId: input.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      action: input.action,
+      entityType: "agent",
+      entityId: input.agentId ?? input.key,
+      ...(actor.agentId ? { agentId: actor.agentId } : {}),
+      ...(actor.runId ? { runId: actor.runId } : {}),
+      details: {
+        key: input.key,
+        status: input.status,
+      },
+    });
+  }
+
+  router.get("/companies/:companyId/built-in-agents", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    res.json(await svc.list(companyId));
+  });
+
+  router.post(
+    "/companies/:companyId/built-in-agents/:key/provision",
+    validate(builtInAgentProvisionSchema),
+    async (req, res) => {
+      const companyId = req.params.companyId as string;
+      const key = req.params.key as string;
+      await assertCanProvisionBuiltInAgents(req, companyId);
+      const state = await svc.ensure(companyId, key, req.body);
+      await logBuiltInAgentMutation(req, {
+        companyId,
+        action: "built_in_agent.provision_requested",
+        key,
+        agentId: state.agentId,
+        status: state.status,
+      });
+      res.json(state);
+    },
+  );
+
+  router.post("/companies/:companyId/built-in-agents/:key/reset", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    const key = req.params.key as string;
+    await assertCanProvisionBuiltInAgents(req, companyId);
+    const state = await svc.reset(companyId, key);
+    await logBuiltInAgentMutation(req, {
+      companyId,
+      action: "built_in_agent.reset",
+      key,
+      agentId: state.agentId,
+      status: state.status,
+    });
+    res.json(state);
+  });
+
+  return router;
+}

server/src/routes/index.ts

@@ -1,6 +1,7 @@
 export { healthRoutes } from "./health.js";
 export { companyRoutes } from "./companies.js";
 export { companySkillRoutes } from "./company-skills.js";
+export { builtInAgentRoutes } from "./built-in-agents.js";
 export { teamsCatalogRoutes } from "./teams-catalog.js";
 export { agentRoutes } from "./agents.js";
 export { projectRoutes } from "./projects.js";

server/src/services/built-in-agents.ts

@@ -2,7 +2,7 @@ import { and, eq, ne } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import { agents, companies } from "@paperclipai/db";
 import type { Agent } from "@paperclipai/shared";
-import { conflict, notFound, unprocessable } from "../errors.js";
+import { conflict, HttpError, notFound, unprocessable } from "../errors.js";
 import { logActivity } from "./activity-log.js";
 import { agentService } from "./agents.js";
 import {
@@ -36,6 +36,20 @@ export interface BuiltInAgentProvisionInput {
   adapterConfig?: Record<string, unknown>;
 }
 
+export interface RequiredBuiltInAgentWarning {
+  code: "built_in_agent_paused";
+  key: string;
+  agentId: string;
+  message: string;
+  pauseReason: string | null;
+}
+
+export interface RequiredBuiltInAgent {
+  definition: BuiltInAgentDefinition;
+  agent: Agent;
+  warning: RequiredBuiltInAgentWarning | null;
+}
+
 const BUILT_IN_AGENT_KEY_PATTERN = /^[a-z][a-z0-9_-]*$/;
 
 const DEFINITIONS = validateBuiltInAgentDefinitions([
@@ -202,6 +216,16 @@ function definitionPatch(definition: BuiltInAgentDefinition, input: BuiltInAgent
   };
 }
 
+function builtInAgentNotConfiguredError(state: BuiltInAgentState) {
+  return new HttpError(412, `Built-in agent is not configured: ${state.definition.key}`, {
+    code: "built_in_agent_not_configured",
+    key: state.definition.key,
+    status: state.status,
+    agentId: state.agentId,
+    featureKeys: state.definition.featureKeys,
+  });
+}
+
 function rowIsBuiltInAgent(row: typeof agents.$inferSelect, key: string) {
   const marker = readBuiltInAgentMarker(row.metadata);
   return marker?.key === key;
@@ -333,11 +357,39 @@ export function builtInAgentService(db: Db) {
     return state(definition, updated as Agent);
   }
 
+  async function reset(companyId: string, key: string) {
+    return reconcileDefinitionDefaults(companyId, key);
+  }
+
+  async function requireBuiltInAgent(companyId: string, key: string): Promise<RequiredBuiltInAgent> {
+    const current = await get(companyId, key);
+    if (!current.agent) throw builtInAgentNotConfiguredError(current);
+    if (current.status === "ready") {
+      return { definition: current.definition, agent: current.agent, warning: null };
+    }
+    if (current.status === "paused") {
+      return {
+        definition: current.definition,
+        agent: current.agent,
+        warning: {
+          code: "built_in_agent_paused",
+          key: current.definition.key,
+          agentId: current.agent.id,
+          message: `Built-in agent ${current.definition.key} is paused; scheduled/background work should be skipped.`,
+          pauseReason: current.pauseReason,
+        },
+      };
+    }
+    throw builtInAgentNotConfiguredError(current);
+  }
+
   return {
     definitions: listBuiltInAgentDefinitions,
     get,
     ensure,
     list,
+    reset,
+    requireBuiltInAgent,
     reconcileDefinitionDefaults,
   };
 }