paperclip/docs/built-in-agents.md

Built-in Agents

Built-in agents are first-party, company-scoped agents that Paperclip can resolve by a stable registry key. They are normal rows in agents, but they carry immutable metadata under metadata.paperclipBuiltInAgent so services can find them without hardcoding a database id.

The first built-ins are briefs and learning. Operators can provision them from the API without going through board hire approval, but the route still requires the same agents:create permission as normal agent creation.

Runtime Model

The subsystem has four layers:

• Registry: server/src/services/built-in-agents.ts defines the static BuiltInAgentDefinition list.
• Marker: server/src/services/built-in-agent-metadata.ts reads and writes metadata.paperclipBuiltInAgent.
• Provisioning service: builtInAgentService(db) finds, creates, updates, resets, and requires built-ins per company.
• Routes: server/src/routes/built-in-agents.ts exposes list, provision, and reset APIs.

Built-in agent state is derived from the marked agent row:

• not_provisioned: no active marked row exists for the company/key.
• needs_setup: a row exists, but adapter config is incomplete for the adapter type.
• ready: adapter config is complete and the agent is not paused.
• paused: the marked row is paused. Scheduled/background work should log the paused warning and skip queueing work.

Use builtInAgentService(db).requireBuiltInAgent(companyId, key) from backend features that need a built-in agent before scheduling work. It throws HTTP 412 with code: "built_in_agent_not_configured" for missing or incomplete agents. Paused agents return the agent plus a built_in_agent_paused warning so callers can pass the warning through to logs or API responses without treating the agent as ready for scheduling.

API

All routes are company-scoped:

• GET /api/companies/:companyId/built-in-agents Lists registry definitions with current company state.
• POST /api/companies/:companyId/built-in-agents/:key/provision Creates or configures the built-in for the company. Body accepts optional adapterType and adapterConfig.
• POST /api/companies/:companyId/built-in-agents/:key/reset Restores registry-owned display/default fields on the marked row while preserving operator adapter setup.

Provision and reset require agents:create. Provision intentionally skips requireBoardApprovalForNewAgents because built-ins are registry-owned system capacity, not ad hoc hires.

Add a New Built-in Agent

1. Add a definition in DEFINITIONS inside server/src/services/built-in-agents.ts.
2. Pick a stable lowercase key using only letters, numbers, _, and -. Do not rename keys after release.
3. Set displayName, shortPurpose, defaultInstructions, defaultRole, and at least one featureKeys entry.
4. Set allowedAdapterTypes to the smallest set that actually works for this built-in.
5. Decide whether the built-in needs a nonzero defaultBudgetMonthlyCents.
6. Add or update tests in server/src/__tests__/built-in-agents.test.ts.
7. If the built-in is surfaced in UI or docs, add those changes in the same PR.
8. Run the focused tests from the repo root with pnpm --filter @paperclipai/server exec vitest run src/__tests__/built-in-agents.test.ts src/__tests__/built-in-agent-routes.test.ts.

Do not write built-in markers directly through generic agent create/update routes. The agent service rejects marker add, remove, and mutation unless the built-in service explicitly opts in.

Worked Example: digest

Hypothetical registry diff:

 const DEFINITIONS = validateBuiltInAgentDefinitions([
   {
     key: "learning",
     displayName: "Learning Agent",
     featureKeys: ["learning"],
     shortPurpose: "Maintains reusable company learning from completed work and recurring patterns.",
     defaultInstructions:
       "You are Paperclip's built-in Learning agent. Extract durable lessons from completed work, preserve useful patterns, and keep learning artifacts grounded in source context.",
     defaultRole: "general",
     allowedAdapterTypes: ["codex_local", "claude_local", "gemini_local", "opencode_local", "process"],
     defaultBudgetMonthlyCents: 0,
   },
+  {
+    key: "digest",
+    displayName: "Digest Agent",
+    featureKeys: ["digest"],
+    shortPurpose: "Summarizes recent company activity into a board-readable digest.",
+    defaultInstructions:
+      "You are Paperclip's built-in Digest agent. Produce short, sourced summaries of recent company activity, decisions, blockers, and next actions.",
+    defaultRole: "general",
+    allowedAdapterTypes: ["codex_local", "claude_local", "process"],
+    defaultBudgetMonthlyCents: 0,
+  },
 ]);

Add focused test coverage:

expect(listBuiltInAgentDefinitions().map((definition) => definition.key).sort()).toEqual([
  "briefs",
  "digest",
  "learning",
]);

If a background job needs the agent:

const { agent, warning } = await builtInAgentService(db).requireBuiltInAgent(companyId, "digest");
if (warning) {
  logger.info({ warning }, "Skipping digest work because built-in agent is paused");
  return;
}

await heartbeatService(db).wakeup(agent.id, {
  source: "automation",
  triggerDetail: "system",
  reason: "Generate company digest",
});

If the agent is missing or not configured, the helper throws:

{
  "error": "Built-in agent is not configured: digest",
  "code": "built_in_agent_not_configured",
  "details": {
    "code": "built_in_agent_not_configured",
    "key": "digest",
    "status": "needs_setup",
    "agentId": "..."
  }
}

PR Checklist

• Registry definition has a stable key and at least one feature key.
• allowedAdapterTypes is intentionally narrow.
• Provisioning does not require board hire approval.
• Generic agent create/update cannot forge or remove the marker.
• Routes remain company-scoped and write activity for mutations.
• Background consumers use requireBuiltInAgent(companyId, key) instead of open-coding marker lookup.
• Paused built-ins skip scheduled/background work and leave an inspectable log or warning.
• Focused tests pass:

pnpm --filter @paperclipai/server exec vitest run src/__tests__/built-in-agents.test.ts src/__tests__/built-in-agent-routes.test.ts

Operational Notes

• One active built-in row per company/key is allowed. Duplicate active markers are treated as a conflict and must be repaired manually.
• Terminated built-in rows are ignored for lookup; provisioning can create a replacement.
• reset restores registry-owned defaults but preserves adapter setup so operators do not lose local model or command configuration.
• Unknown marker keys are ignored during startup reconciliation. This prevents removed experimental built-ins from breaking server boot.
• Feature code should treat 412 built_in_agent_not_configured as an operator setup problem, not as a 500.