Files
PaperClipAI/ui/src/components/ConfigureBuiltInAgentModal.test.tsx
T
DottaandPaperclip 8b6a06ee25 [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>
2026-07-09 16:29:30 -05:00

251 lines
8.2 KiB
TypeScript

// @vitest-environment jsdom
import { flushSync } from "react-dom";
import { createRoot, type Root } from "react-dom/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { ConfigureBuiltInAgentModal } from "./ConfigureBuiltInAgentModal";
import type { BuiltInAgentState } from "@/api/builtInAgents";
const provisionMock = vi.hoisted(() => vi.fn());
const updateMock = vi.hoisted(() => vi.fn());
const adapterModelsMock = vi.hoisted(() => vi.fn());
vi.mock("@/api/builtInAgents", async (importOriginal) => {
const actual = await importOriginal<typeof import("@/api/builtInAgents")>();
return { ...actual, builtInAgentsApi: { list: vi.fn(), provision: provisionMock, reset: vi.fn() } };
});
vi.mock("@/api/agents", () => ({
agentsApi: { update: updateMock, adapterModels: adapterModelsMock },
}));
vi.mock("@/adapters/metadata", () => ({
listAdapterOptions: () => [
{ value: "codex_local", label: "Codex" },
{ value: "claude_local", label: "Claude" },
{ value: "process", label: "Process" },
],
}));
// Stub the shared pickers so the test can drive them without the full form.
vi.mock("@/components/AgentConfigForm", () => ({
AdapterTypeDropdown: ({ value }: { value: string }) => (
<div data-testid="adapter-dropdown" data-value={value} />
),
ModelDropdown: ({ value, onChange }: { value: string; onChange: (v: string) => void }) => (
<input
data-testid="model-input"
value={value}
onChange={(e) => onChange((e.target as HTMLInputElement).value)}
/>
),
}));
vi.mock("@/components/agent-config-primitives", () => ({
Field: ({ label, children }: { label: string; children: React.ReactNode }) => (
<label>
{label}
{children}
</label>
),
}));
function makeState(overrides: Partial<BuiltInAgentState> = {}): BuiltInAgentState {
return {
definition: {
key: "briefs",
displayName: "Briefs Agent",
featureKeys: ["briefs"],
shortPurpose: "Prepares briefs.",
defaultInstructions: "…",
defaultRole: "general",
allowedAdapterTypes: ["codex_local", "claude_local"],
defaultBudgetMonthlyCents: 0,
},
status: "not_provisioned",
agentId: null,
agent: null,
pauseReason: null,
...overrides,
};
}
async function flushReact() {
for (let index = 0; index < 6; index += 1) {
await Promise.resolve();
await new Promise((resolve) => window.setTimeout(resolve, 0));
}
flushSync(() => {});
}
function findButton(text: string): HTMLButtonElement | undefined {
return Array.from(document.body.querySelectorAll("button")).find((b) =>
b.textContent?.includes(text),
) as HTMLButtonElement | undefined;
}
describe("ConfigureBuiltInAgentModal (PAP-12978)", () => {
let container: HTMLDivElement;
let root: Root | null = null;
const onOpenChange = vi.fn();
const onConfigured = vi.fn();
async function renderModal(state: BuiltInAgentState = makeState()) {
root = createRoot(container);
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
flushSync(() => {
root!.render(
<QueryClientProvider client={queryClient}>
<ConfigureBuiltInAgentModal
companyId="c1"
state={state}
open
onOpenChange={onOpenChange}
onConfigured={onConfigured}
/>
</QueryClientProvider>,
);
});
await flushReact();
}
beforeEach(() => {
container = document.createElement("div");
document.body.appendChild(container);
provisionMock.mockReset();
updateMock.mockReset();
adapterModelsMock.mockReset().mockResolvedValue([]);
onOpenChange.mockReset();
onConfigured.mockReset();
});
afterEach(() => {
flushSync(() => {
root?.unmount();
});
root = null;
container.remove();
});
it("disables submit until a model is chosen, then provisions with adapter + model", async () => {
provisionMock.mockResolvedValue({ ...makeState(), status: "ready", agentId: "a1" });
await renderModal();
const submit = findButton("Configure");
expect(submit).toBeTruthy();
expect(submit!.disabled).toBe(true);
const modelInput = document.body.querySelector('[data-testid="model-input"]') as HTMLInputElement;
expect(modelInput).toBeTruthy();
const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value")!.set!;
flushSync(() => {
setter.call(modelInput, "gpt-5");
modelInput.dispatchEvent(new Event("input", { bubbles: true }));
});
await flushReact();
const submitReady = findButton("Configure")!;
expect(submitReady.disabled).toBe(false);
flushSync(() => {
submitReady.dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
await flushReact();
expect(provisionMock).toHaveBeenCalledWith("c1", "briefs", {
adapterType: "codex_local",
adapterConfig: { model: "gpt-5" },
});
expect(onConfigured).toHaveBeenCalled();
expect(onOpenChange).toHaveBeenCalledWith(false);
});
it("sends the budget with provisioning so approval-gated setup preserves it", async () => {
provisionMock.mockResolvedValue({
...makeState(),
status: "pending_approval",
agentId: "a1",
approval: { id: "approval-1", status: "pending" },
});
await renderModal();
const modelInput = document.body.querySelector('[data-testid="model-input"]') as HTMLInputElement;
const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value")!.set!;
flushSync(() => {
setter.call(modelInput, "gpt-5");
modelInput.dispatchEvent(new Event("input", { bubbles: true }));
});
await flushReact();
const budgetInput = document.body.querySelector('input[type="number"]') as HTMLInputElement;
flushSync(() => {
setter.call(budgetInput, "50");
budgetInput.dispatchEvent(new Event("input", { bubbles: true }));
});
await flushReact();
flushSync(() => {
findButton("Configure")!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
await flushReact();
expect(provisionMock).toHaveBeenCalled();
expect(provisionMock).toHaveBeenCalledWith("c1", "briefs", {
adapterType: "codex_local",
adapterConfig: { model: "gpt-5" },
budgetMonthlyCents: 5000,
});
expect(updateMock).not.toHaveBeenCalled();
});
it("provisions non-model adapters so command fields can be completed later", async () => {
provisionMock.mockResolvedValue({ ...makeState(), status: "needs_setup", agentId: "a1" });
await renderModal(makeState({
definition: {
...makeState().definition,
allowedAdapterTypes: ["process"],
},
}));
expect(document.body.textContent).toContain("needs command or endpoint fields");
expect(document.body.querySelector('[data-testid="model-input"]')).toBeNull();
const submit = findButton("Provision");
expect(submit).toBeTruthy();
expect(submit!.disabled).toBe(false);
flushSync(() => {
submit!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
await flushReact();
expect(provisionMock).toHaveBeenCalledWith("c1", "briefs", {
adapterType: "process",
adapterConfig: {},
});
expect(onConfigured).toHaveBeenCalled();
expect(onOpenChange).toHaveBeenCalledWith(false);
});
it("surfaces provision errors inline instead of closing", async () => {
const { ApiError } = await import("@/api/client");
provisionMock.mockRejectedValue(new ApiError("Adapter not allowed", 422, null));
await renderModal();
const modelInput = document.body.querySelector('[data-testid="model-input"]') as HTMLInputElement;
const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value")!.set!;
flushSync(() => {
setter.call(modelInput, "gpt-5");
modelInput.dispatchEvent(new Event("input", { bubbles: true }));
});
await flushReact();
flushSync(() => {
findButton("Configure")!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
await flushReact();
expect(document.body.textContent).toContain("Adapter not allowed");
expect(onOpenChange).not.toHaveBeenCalledWith(false);
});
});