[codex] Add built-in agents and Reflection Coach bundle (#9206)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Operators need first-party agent capabilities for repeatable company
work, not just manually created one-off agents.
> - Built-in agents need to behave like normal company-scoped agents
while preserving approval gates, permissions, budgets, and audit trails.
> - Reflection and coaching work also needs bundled instructions, skill
content, and a routine so the feature can be installed and reset
predictably.
> - The API, database, UI, portability, and tests all need to agree on
the built-in lifecycle from not provisioned through setup, approval,
ready, paused, and reset.
> - This pull request adds built-in agent provisioning and the
Reflection Coach bundle end-to-end.
> - The benefit is a safer first-party path for Paperclip-managed agents
without bypassing the same governance model used for operator-created
agents.

## Linked Issues or Issue Description

No public GitHub issue was found for this exact built-in agent and
Reflection Coach bundle work.

Problem/motivation:
- Paperclip did not have a first-party built-in agent lifecycle for
product-owned agents.
- Bundled agent resources such as default instructions, skills, and
routines needed managed ownership and reset semantics.
- Approval-gated companies needed built-in setup to preserve requested
adapter, budget, manager, and permission state through board approval.
- The board UI needed clear built-in badges, setup affordances,
readiness state, and bundle status without exposing secrets.

Proposed solution:
- Add a company-scoped built-in agent registry,
provisioning/reset/reconcile/status APIs, and Reflection Coach bundled
resources.
- Track bundled managed resources in the database with idempotent
migration behavior.
- Reuse existing agent approval, authorization, budget, and activity-log
paths instead of creating a bypass.
- Add UI setup, badges, gates, bundle panels, and route coverage for
built-in agents.

Duplicate search:
- Searched GitHub PRs for `built-in agents Reflection Coach
repo:paperclipai/paperclip`; only this PR was returned.
- Searched GitHub issues for the same query; no public issues were
returned.

## What Changed

- Added built-in agent definitions, lifecycle state derivation,
provisioning, reset, reconcile, status, and routine-control routes.
- Added the `built_in_managed_resources` migration and schema exports
for bundled instructions, skill, and routine ownership.
- Added the Reflection Coach built-in bundle with default instructions,
skill catalog content, routine template, default permissions, and
managed-resource drift handling.
- Added approval-aware provisioning behavior that preserves requested
adapter config, budgets, manager assignment, and built-in permissions
through hire approval.
- Added authorization and mutation gates for built-in agent and skill
changes, including consented Reflection Coach change paths.
- Added UI surfaces for built-in agent setup, roster/detail badges,
readiness gates, bundle status, routine controls, and route filtering.
- Added company import/export and validator coverage for built-in
managed resources and low-trust/red-team presets.
- Addressed Greptile follow-ups for pending approval reconciliation,
consent-gate error propagation, config-read authorization fallback,
approval-path manager preservation, and non-model adapter provisioning.

## Verification

Local verification:
- `git diff --check public/master..HEAD` passed.
- `pnpm check:token-gates` passed with all gates clean.
- `pnpm exec vitest run
ui/src/components/ConfigureBuiltInAgentModal.test.tsx` passed: 1 file, 4
tests.
- `pnpm exec vitest run ui/src/components/EntityRow.test.tsx
ui/src/pages/Agents.test.tsx ui/src/components/BuiltInAgentGate.test.tsx
ui/src/components/ConfigureBuiltInAgentModal.test.tsx
ui/src/components/BuiltInBundlePanel.test.tsx
ui/src/pages/InstanceExperimentalSettings.test.tsx
ui/src/pages/Routines.test.tsx` passed: 7 files, 64 tests.
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/built-in-agents.test.ts
src/__tests__/authorization-service.test.ts
src/__tests__/company-skills-routes.test.ts` passed: 3 files, 91 tests.
- `pnpm --filter @paperclipai/db check:migrations` passed.
- `pnpm -r typecheck` passed after the rebase; `pnpm --filter ui
typecheck` passed after the final UI review fix.

Remote verification on latest head
`1c61f693a4ec881d739022b0e75a8ca8bf8c2cd8`:
- Merge state: `CLEAN`.
- Greptile: `5/5`, zero unresolved Greptile threads.
- PR check rollup: all checks successful, neutral, or skipped as
expected.
- Passing gates include Build, Typecheck + Release Registry, all server
shards, all workspace shards, all serialized server suites, e2e, Canary
Dry Run, policy, review, verify, Socket, Superagent, and Snyk.

## Risks

- This adds a new managed-resource table and migration; the migration
uses idempotent create/add/index guards and passed migration safety
checks.
- Built-in agent provisioning touches approval and authorization paths;
tests cover pending approval preservation, stale retry rejection,
consent gates, and config-read fallback behavior.
- Reflection Coach creates managed instructions, skill, and routine
resources; drift/reset behavior is covered by service tests and redacted
API responses.
- Non-model adapter setup now provisions a `needs_setup` built-in row
before command/endpoint fields are complete; this matches the server
lifecycle and is covered by the setup modal regression test.

## Model Used

OpenAI Codex coding agent based on GPT-5. Exact hosted model ID,
context-window size, and reasoning-mode labels are not exposed in this
runtime; tool use, shell execution, GitHub CLI/API access, and local
code editing were enabled.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/src/api/builtInAgents.ts

@@ -0,0 +1,165 @@
+import type { Agent, Approval } from "@paperclipai/shared";
+import { api } from "./client";
+
+/**
+ * Lifecycle of a built-in agent, derived server-side from row existence,
+ * adapter-config completeness, board-approval state, and `pausedAt`.
+ *
+ * `not_provisioned → pending_approval → needs_setup → ready ⇄ paused`
+ *
+ * `pending_approval` only occurs when the company requires board approval for
+ * new agents; otherwise provisioning goes straight to `needs_setup`/`ready`.
+ */
+export type BuiltInAgentStatus =
+  | "not_provisioned"
+  | "pending_approval"
+  | "needs_setup"
+  | "ready"
+  | "paused";
+
+/**
+ * Redacted bundle metadata returned alongside a built-in agent that ships a
+ * managed resource bundle (instructions + skill + routine). The server strips
+ * file bodies to key lists; the UI only needs the identity/labels to render the
+ * bundle status panel. Present only on bundle-backed built-ins (Reflection
+ * Coach); flat built-ins (briefs/learning) omit it.
+ */
+export interface BuiltInAgentBundleMeta {
+  stockVersion: string;
+  instructions: { entryFile: string; files: string[] };
+  skill: {
+    skillKey: string;
+    displayName: string;
+    slug: string;
+    canonicalKey: string;
+    files: string[];
+  };
+  routine: {
+    routineKey: string;
+    title: string;
+    status: "active" | "paused";
+    triggerCount: number;
+    scheduleLabel?: string;
+  };
+}
+
+export interface BuiltInAgentDefinition {
+  key: string;
+  displayName: string;
+  featureKeys: string[];
+  shortPurpose: string;
+  defaultInstructions: string;
+  defaultRole: string;
+  allowedAdapterTypes?: string[];
+  defaultBudgetMonthlyCents?: number;
+  bundle?: BuiltInAgentBundleMeta;
+}
+
+/** Managed resources a bundle materializes; drift is tracked per kind. */
+export type BuiltInManagedResourceKind = "instructions" | "skill" | "routine";
+
+/**
+ * Drift status of one managed resource versus the shipped stock default:
+ * - `missing` — expected resource absent; a reconcile will recreate it.
+ * - `stock_current` — present and byte-identical to the shipped default.
+ * - `stock_update_available` — unedited, but Paperclip shipped a newer default.
+ * - `operator_modified` — operator-edited; reconcile preserves these edits.
+ */
+export type BuiltInManagedResourceStockStatus =
+  | "missing"
+  | "stock_current"
+  | "stock_update_available"
+  | "operator_modified";
+
+export interface BuiltInManagedResourceState {
+  resourceKind: BuiltInManagedResourceKind;
+  resourceKey: string;
+  resourceId: string | null;
+  stockVersion: string;
+  stockHash: string;
+  currentHash: string | null;
+  stockStatus: BuiltInManagedResourceStockStatus;
+  /** True when an unedited resource has a newer shipped default to apply. */
+  updateAvailable: boolean;
+  /** True when the resource has drifted and can be reset to the default. */
+  resetAvailable: boolean;
+  changedFiles?: string[];
+  /** True when the managed weekly schedule is active and can create background work. */
+  scheduleEnabled?: boolean;
+  /** Pending request_confirmation for a Reflection Coach update proposal, when one exists. */
+  pendingUpdateInteractionId?: string | null;
+  /** Issue containing the pending proposal interaction. */
+  pendingUpdateIssueId?: string | null;
+  pendingUpdateIssueIdentifier?: string | null;
+}
+
+export interface BuiltInAgentState {
+  definition: BuiltInAgentDefinition;
+  status: BuiltInAgentStatus;
+  agentId: string | null;
+  agent: Agent | null;
+  pauseReason: string | null;
+  /** Per-resource drift/readiness for bundle-backed built-ins (may be empty). */
+  resources?: BuiltInManagedResourceState[];
+  /** Present when provisioning queued a board hire approval (HTTP 202). */
+  approval?: Approval | null;
+}
+
+export interface BuiltInAgentProvisionInput {
+  adapterType?: string;
+  adapterConfig?: Record<string, unknown>;
+  budgetMonthlyCents?: number;
+}
+
+/**
+ * Selectors accepted by the reset endpoint. `agent` resets the agent config
+ * (adapter/model/budget defaults) only; the resource kinds each reset a single
+ * managed resource back to its shipped default. Omitting the array resets
+ * everything (the agent-level "Reset to defaults" button).
+ */
+export type BuiltInResetResource = "agent" | BuiltInManagedResourceKind;
+
+/**
+ * Error `code` thrown as HTTP 412 by `requireBuiltInAgent` on the server when a
+ * feature needs a built-in agent that is missing or not fully configured. The
+ * configure-on-first-use modal is triggered from this signal.
+ */
+export const BUILT_IN_AGENT_NOT_CONFIGURED_CODE = "built_in_agent_not_configured";
+
+/**
+ * Warning `code` returned alongside a paused built-in agent so callers can
+ * surface the use-while-paused toast without treating the agent as ready.
+ */
+export const BUILT_IN_AGENT_PAUSED_CODE = "built_in_agent_paused";
+
+export const builtInAgentsApi = {
+  list: (companyId: string) =>
+    api.get<BuiltInAgentState[]>(`/companies/${companyId}/built-in-agents`),
+  provision: (companyId: string, key: string, input: BuiltInAgentProvisionInput = {}) =>
+    api.post<BuiltInAgentState>(`/companies/${companyId}/built-in-agents/${key}/provision`, input),
+  /**
+   * Reset built-in defaults. Pass `resources` to scope the reset to specific
+   * managed resources (e.g. `["skill"]`); omit it to reset the whole agent +
+   * bundle. A single-resource reset re-applies that resource's newest shipped
+   * default — the same path used for both "reset drifted edits" and "apply an
+   * available stock update".
+   */
+  reset: (companyId: string, key: string, resources?: BuiltInResetResource[]) =>
+    api.post<BuiltInAgentState>(
+      `/companies/${companyId}/built-in-agents/${key}/reset`,
+      resources ? { resources } : {},
+    ),
+  /**
+   * Re-materialize the bundle. Applies the newest shipped defaults to unedited
+   * (`stock_update_available`) and `missing` resources while preserving
+   * `operator_modified` edits — it is the safe "apply available updates" path.
+   */
+  reconcile: (companyId: string, key: string) =>
+    api.post<BuiltInAgentState>(`/companies/${companyId}/built-in-agents/${key}/reconcile`, {}),
+  runRoutine: (companyId: string, key: string, routineKey: string) =>
+    api.post<unknown>(`/companies/${companyId}/built-in-agents/${key}/routines/${routineKey}/run`, {}),
+  enableRoutineSchedule: (companyId: string, key: string, routineKey: string) =>
+    api.post<BuiltInAgentState>(`/companies/${companyId}/built-in-agents/${key}/routines/${routineKey}/enable`, {}),
+  disableRoutineSchedule: (companyId: string, key: string, routineKey: string) =>
+    api.post<BuiltInAgentState>(`/companies/${companyId}/built-in-agents/${key}/routines/${routineKey}/disable`, {}),
+};