Files
PaperClipAI/server/src/__tests__/built-in-agents.test.ts
T
DottaandClaude Opus 5.5 6383eb8033 fix(authz): require board authority for agent budget changes on every route (#20213)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Budgets stop agent spending. The budget hard stop is a control-plane
invariant
> - The budget routes (`PATCH /api/agents/:id/budgets`, `PATCH
/api/companies/:id/budgets`) are board-only
> - `PATCH /api/agents/:id` also accepts `budgetMonthlyCents`, and the
configuration service writes the agent budget policy from it. That route
had no board check for the field
> - So an agent, such as a CEO, a manager or the agent itself, can
change a monthly budget without a board user. This is a second route
around a board-only control, like the pause bypass that #20164 fixed
> - This pull request applies the budget route authority to every route
that writes an agent budget, and gives agents the final board-only
denial with a link to the budget page (#20151)
> - The benefit is that only the board changes budgets, and an agent
that asks gets a final answer that it can pass to the person

## Linked Issues or Issue Description

Refs #17857 (earlier fix, now in conflict with master; this PR rebases
it and adds the budget page link). Refs #20164 and #20151 (same pattern
for PATCH status and board-only denials).

**What happened**

An agent can send `PATCH /api/agents/{id}` with `budgetMonthlyCents`.
The route accepts it, and the configuration service writes the agent
budget policy. This works for the agent's own budget and, with update
permission, for other agents. The same field also reaches budget policy
through a configuration rollback, direct agent creation, an immediate
hire and a built-in agent provision. A chat eval
(`budgets-costs.resolve-budget`) found the route.

**Expected behavior**

Only a board user can change an active budget, as on the dedicated
budget routes. An agent gets `403` with code `board_access_required`.
The denial says it is final and links the agent's budget tab
(`/<prefix>/agents/<id>/budgets`) or the company budgets page
(`/<prefix>/activity/budgets`). An agent can still propose a budget in a
hire that waits for board approval. The approving board user activates
it.

**Steps to reproduce**

1. On master, authenticate as an agent of a company (for example the
CEO).
2. Send `PATCH /api/agents/{agentId}` with body `{"budgetMonthlyCents":
5000}`, for its own id or for another agent.
3. See `200`. The agent budget policy changes with no board action.
4. The new route tests reproduce this: on master source they fail with
`expected 200 to be 403`.

## What Changed

- `PATCH /api/agents/:id`: a changed `budgetMonthlyCents` requires a
board actor. An unchanged amount with other edits still works.
- Configuration rollback: a rollback that changes the budget requires a
board actor.
- `POST /api/companies/:id/agents` and an immediate `agent-hires`: a
positive budget requires a board actor. A hire that needs board approval
keeps the proposed budget and does not activate it before approval.
- Built-in agent provision: a budget override requires a board actor.
- `prepareAgentConfiguration` rejects an agent-originated budget change
again (defense in depth). An agent rollback with an unchanged amount
does not rewrite the policy.
- Board writes keep the actual operator identity. The initial hire
budget is saved in the hire transaction.
- `assertBoard` and `boardAccessRequired` take an optional board page.
Budget denials link the agent's budget tab or the company budgets page,
not the general agent profile.
- Agent access map updated.
- This includes the four commits of #17857 (f970f6b01f, 8c06aba41c,
e5682d22fa, b6cd49d4b6), rebased onto master with the conflicts
resolved, then squashed.

## Verification

- Red on master source, same tests: 12 budget tests fail. The PATCH
tests fail with `expected 200 to be 403` for the agent's own budget and
for a CEO on another agent. Built-in provision fails with `expected 200
to be 403`. Creation and immediate hire fail with `expected 201 to be
403`.
- Green with the fix: `cd server && npx vitest run
src/__tests__/agent-permissions-routes.test.ts
src/__tests__/built-in-agent-routes.test.ts
src/__tests__/built-in-agents.test.ts
src/__tests__/agent-hire-idempotency-routes.test.ts
src/__tests__/board-access-denial.test.ts
src/__tests__/agent-budget-configuration.test.ts`: 222 passed.
- `src/modules/agent-lifecycle/__tests__/lifecycle.test.ts` (embedded
Postgres): 76 passed.
- `agent-skills-routes`, `agent-adapter-validation-routes`,
`openapi-routes`, `agent-cross-tenant-authz-routes`: 275 passed.
- `node scripts/check-maps.mjs`: passed. `git diff --check`: passed.
- Server `tsc --noEmit`: no errors in changed files. One error in
`native-session-executor.ts` comes from a linked runner build in the
local worktree, not from this change. CI runs the full typecheck.

## Risks

- Agent clients that set an active budget directly now get `403`. They
must propose the budget in an approval-gated hire, or ask a board user.
- Agent creation with no budget or a zero budget is not changed. Pending
hire budgets do not activate before approval.
- Trusted internal plugin provisioning keeps its prior behavior and gets
no board identity.
- No schema or migration change.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code
execution, in Claude Code. The rebased commits from #17857 were first
written with OpenAI `gpt-6.1-sol` through Codex.

## 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
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 02:50:16 -06:00

1859 lines
77 KiB
TypeScript

import { createAgentLifecycle, configureAgentLifecycle } from "../services/agent-lifecycle.js";
import fs from "node:fs/promises";
import { fileHash } from "../services/agent-file-store.js";
import { stockHash } from "../services/managed-resource-drift.js";
import { randomUUID } from "node:crypto";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import path from "node:path";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import { and, eq, sql } from "drizzle-orm";
import {
activityLog,
heartbeatRuns,
agentWakeupRequests,
routineRuns,
agentConfigRevisions,
agents,
approvals,
budgetPolicies,
builtInManagedResources,
companies,
companyMemberships,
companySkillVersions,
companySkills,
createDb,
issueThreadInteractions,
issues,
principalPermissionGrants,
routines,
routineTriggers,
} from "@paperclipai/db";
import { readPaperclipSkillSyncPreference } from "@paperclipai/adapter-utils/server-utils";
import {
getEmbeddedPostgresTestSupport,
startEmbeddedPostgresTestDatabase,
} from "./helpers/embedded-postgres.js";
import { agentInstructionRevisionService } from "../services/agent-instruction-revisions.js";
import { agentInstructionsService } from "../services/agent-instructions.ts";
import { agentService } from "../services/agents.ts";
import { approvalService } from "../services/approvals.ts";
import {
builtInAgentService as createBuiltInAgentService,
deriveBuiltInAgentStatus,
listBuiltInAgentDefinitions,
readBuiltInTextWithFallback,
reconcileBuiltInAgentsOnStartup,
validateBuiltInAgentDefinitions,
} from "../services/built-in-agents.ts";
import { readBuiltInAgentMarker, withBuiltInAgentMarker } from "../lib/built-in-agent-metadata.ts";
import { issueThreadInteractionService } from "../services/issue-thread-interactions.ts";
const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
const BUILT_IN_MARKER_UNIQUE_INDEX = "agents_company_built_in_agent_key_unique_idx";
// Mirrors migration 0192. Used to drop/restore the partial unique index when a
// test needs to simulate legacy duplicates that predate the constraint.
const BUILT_IN_MARKER_UNIQUE_INDEX_DDL = `
CREATE UNIQUE INDEX IF NOT EXISTS "${BUILT_IN_MARKER_UNIQUE_INDEX}"
ON "agents" ("company_id", ((metadata -> 'paperclipBuiltInAgent' ->> 'key')))
WHERE (metadata -> 'paperclipBuiltInAgent' ->> 'key') IS NOT NULL
AND status <> 'terminated'
`;
function issuePrefix(id: string) {
return `T${id.replace(/-/g, "").slice(0, 6).toUpperCase()}`;
}
if (!embeddedPostgresSupport.supported) {
console.warn(
`Skipping embedded Postgres built-in agent tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
);
}
describe("built-in agent asset loading", () => {
it("uses the first readable candidate path", () => {
const dir = mkdtempSync(path.join(tmpdir(), "paperclip-built-in-agent-"));
try {
const first = path.join(dir, "missing.md");
const second = path.join(dir, "asset.md");
writeFileSync(second, "asset text", "utf8");
expect(readBuiltInTextWithFallback(`asset:${randomUUID()}`, [first, second], "fallback text")).toBe("asset text");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("falls back instead of throwing when built-in agent files are missing", () => {
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
const label = `missing:${randomUUID()}`;
try {
expect(readBuiltInTextWithFallback(label, [path.join(tmpdir(), label, "AGENTS.md")], "fallback text")).toBe(
"fallback text",
);
expect(warn).toHaveBeenCalledWith(expect.stringContaining(`Built-in agent asset ${label} was not readable`));
} finally {
warn.mockRestore();
}
});
it("warns about non-missing read errors before falling back", () => {
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
const dir = mkdtempSync(path.join(tmpdir(), "paperclip-built-in-agent-"));
const label = "unreadable:" + randomUUID();
try {
const directoryPath = path.join(dir, "asset.md");
mkdirSync(directoryPath);
expect(readBuiltInTextWithFallback(label, [directoryPath], "fallback text")).toBe("fallback text");
expect(warn).toHaveBeenCalledWith(expect.stringContaining("read error on " + directoryPath + ":"));
expect(warn).toHaveBeenCalledWith(
expect.stringContaining("Built-in agent asset " + label + " was not readable"),
);
} finally {
warn.mockRestore();
rmSync(dir, { recursive: true, force: true });
}
});
});
describeEmbeddedPostgres("built-in agents", () => {
let db!: ReturnType<typeof createDb>;
let lifecycleWorker: ReturnType<typeof configureAgentLifecycle>;
function builtInAgentService(database: typeof db) {
const service = createBuiltInAgentService(database);
return { ...service,
async ensure(...args: Parameters<typeof service.ensure>) {
const result = await service.ensure(...args);
if (result.agentId) await lifecycleWorker.process(result.agentId);
return service.get(args[0], args[1]);
},
async get(...args: Parameters<typeof service.get>) {
const result = await service.get(...args);
if (result.agentId) await lifecycleWorker.process(result.agentId);
return service.get(...args);
},
};
}
let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
let runnerSelectionSpy: { mockRestore(): void } | undefined;
const runnerTarget = { driver: "local", platform: "linux", architecture: "x64" };
const instructionOperator = { type: "board", userId: "local-board", source: "local_implicit" } as const;
async function writeInstructionEntry(agent: { id: string; companyId: string }, entryFile: string, content: string) {
const service = agentInstructionRevisionService(db);
const target = { companyId: agent.companyId, agentId: agent.id };
const baseline = await service.readCurrent(target, instructionOperator);
await service.commit({ ...target, entryFile, content, baseRevisionId: baseline?.revision.id ?? null, source: "board" }, instructionOperator);
const refreshed = await agentService(db).getById(agent.id);
return { adapterConfig: refreshed!.adapterConfig };
}
beforeAll(async () => {
tempDb = await startEmbeddedPostgresTestDatabase("paperclip-built-in-agents-");
db = createDb(tempDb.connectionString);
lifecycleWorker = configureAgentLifecycle(db, { requiredPluginIds: async () => [], runPlugin: async () => "complete", runHost: async () => "complete" });
}, 20_000);
beforeEach(async () => {
runnerTarget.platform = "linux";
runnerTarget.architecture = "x64";
const selection = await import("../services/agent-runner-selection.js");
runnerSelectionSpy = vi.spyOn(selection, "resolveNewAgentRunnerForCompany").mockImplementation(async (_db, _companyId, input) =>
selection.resolveNewAgentRunner({ ...input, target: runnerTarget }));
});
afterEach(async () => {
runnerSelectionSpy?.mockRestore();
await lifecycleWorker.sweep();
await db.delete(routineTriggers);
await db.delete(routines);
await db.delete(issueThreadInteractions);
await db.delete(issues);
await db.delete(builtInManagedResources);
await db.delete(companySkillVersions);
await db.delete(companySkills);
await db.delete(principalPermissionGrants);
await db.delete(companyMemberships);
await db.delete(agentConfigRevisions);
await db.delete(activityLog);
await db.delete(approvals);
await db.delete(agents);
await db.delete(budgetPolicies);
await db.delete(companies);
// Some tests drop the built-in marker unique index to simulate legacy
// (pre-migration 0192) duplicates; restore it now that all rows are gone.
await db.execute(sql.raw(BUILT_IN_MARKER_UNIQUE_INDEX_DDL));
});
afterAll(async () => {
await lifecycleWorker.stop();
await tempDb?.cleanup();
});
async function permissionKeysForAgent(agentId: string) {
const grants = await db
.select()
.from(principalPermissionGrants)
.where(eq(principalPermissionGrants.principalId, agentId));
return grants.map((grant) => grant.permissionKey).sort();
}
async function seedCompany(options: { requireApproval?: boolean } = {}) {
const companyId = randomUUID();
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: issuePrefix(companyId),
defaultResponsibleUserId: "responsible-user",
requireBoardApprovalForNewAgents: options.requireApproval ?? true,
});
return companyId;
}
it("validates the static registry and rejects invalid definitions", () => {
const definitions = listBuiltInAgentDefinitions();
expect(definitions.map((definition) => definition.key).sort()).toEqual(["briefs", "learning", "reflection-coach", "summarizer"]);
const summarizer = definitions.find((definition) => definition.key === "summarizer");
expect(summarizer).toMatchObject({
defaultAdapterType: "claude_local",
defaultAdapterConfig: { model: "claude-haiku-4-5" },
});
expect(summarizer?.defaultRuntimeConfig).toBeUndefined();
expect(() => validateBuiltInAgentDefinitions([
{
key: "briefs",
displayName: "Briefs Agent",
featureKeys: ["briefs"],
shortPurpose: "One",
defaultInstructions: "Do work",
defaultRole: "general",
},
{
key: "briefs",
displayName: "Duplicate",
featureKeys: ["duplicate"],
shortPurpose: "Two",
defaultInstructions: "Do work",
defaultRole: "general",
},
])).toThrow("Duplicate built-in agent key");
expect(() => validateBuiltInAgentDefinitions([
{
key: "Bad Key",
displayName: "Bad",
featureKeys: ["bad"],
shortPurpose: "Bad",
defaultInstructions: "Bad",
defaultRole: "general",
},
])).toThrow("Invalid built-in agent key");
expect(() => validateBuiltInAgentDefinitions([
{
key: "bad-default",
displayName: "Bad default",
featureKeys: ["bad-default"],
shortPurpose: "Bad default adapter",
defaultInstructions: "Do work",
defaultRole: "general",
allowedAdapterTypes: ["codex_local"],
defaultAdapterType: "claude_local",
},
])).toThrow("defaultAdapterType must be allowed");
});
it("retains the actual operator on a provisioned existing agent budget", async () => {
const companyId = await seedCompany({ requireApproval: false });
const svc = builtInAgentService(db);
const original = await svc.ensure(companyId, "briefs");
await svc.provision(companyId, "briefs", { budgetMonthlyCents: 5000 }, { requestedByUserId: "budget-operator" });
expect(await db.select().from(budgetPolicies).where(eq(budgetPolicies.scopeId, original.agentId!))).toMatchObject([{ amount: 5000, createdByUserId: "budget-operator" }]);
});
it.each([{ platform: "linux", architecture: "x64" }, { platform: "linux", architecture: "arm64" }, { platform: "darwin", architecture: "arm64" }, { platform: "darwin", architecture: "x64" }])("lazily provisions one agent per company/key and updates the same row on setup ($platform/$architecture)", async ({ platform, architecture }) => {
runnerTarget.platform = platform;
runnerTarget.architecture = architecture;
const companyId = await seedCompany();
const svc = builtInAgentService(db);
const created = await svc.ensure(companyId, "briefs");
expect(created.status).toBe("needs_setup");
expect(created.agentId).toBeTruthy();
expect(created.agent).toMatchObject({
companyId,
name: "Briefs Agent",
adapterConfig: {},
status: "idle",
});
expect(readBuiltInAgentMarker(created.agent?.metadata)).toEqual({
key: "briefs",
featureKeys: ["briefs"],
});
const configured = await svc.ensure(companyId, "briefs", {
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
});
expect(configured.status).toBe("ready");
expect(configured.agentId).toBe(created.agentId);
expect(configured.agent).toMatchObject({
adapterType: "paperclip_runner",
adapterConfig: { provider: "codex", model: "gpt-5.4" },
});
const reconciled = await svc.ensure(companyId, "briefs");
expect(reconciled.status).toBe("ready");
expect(reconciled.agent).toMatchObject({
adapterType: "paperclip_runner",
adapterConfig: { provider: "codex", model: "gpt-5.4" },
});
const rows = await db.select().from(agents).where(eq(agents.companyId, companyId));
expect(rows).toHaveLength(1);
});
it("keeps existing legacy and native built-in runners through unrelated edits and startup", async () => {
const companyId = await seedCompany({ requireApproval: false });
const svc = builtInAgentService(db);
const savedSettings = { model: "gpt-5.5", modelReasoningEffort: "high", timeoutSec: 123 };
const created = await svc.ensure(companyId, "briefs", { adapterType: "codex_local", adapterConfig: savedSettings, runner: "legacy" });
expect(created.agent?.adapterType).toBe("codex_local");
await svc.ensure(companyId, "briefs", { budgetMonthlyCents: 100 });
await reconcileBuiltInAgentsOnStartup(db);
const legacy = await svc.get(companyId, "briefs");
expect(legacy.agent?.adapterType).toBe("codex_local");
expect(legacy.agent?.adapterConfig).toEqual(created.agent?.adapterConfig);
const switched = await svc.ensure(companyId, "briefs", { runner: "paperclip" });
expect(switched.agent).toMatchObject({ adapterType: "paperclip_runner", adapterConfig: { provider: "codex", ...savedSettings } });
await svc.ensure(companyId, "briefs", { budgetMonthlyCents: 200 });
await reconcileBuiltInAgentsOnStartup(db);
expect((await svc.get(companyId, "briefs")).agent?.adapterConfig).toEqual(switched.agent?.adapterConfig);
const switchedBack = await svc.ensure(companyId, "briefs", { runner: "legacy" });
expect(switchedBack.agent).toMatchObject({ adapterType: "codex_local", adapterConfig: savedSettings });
const switchedAgain = await svc.ensure(companyId, "briefs", { runner: "paperclip" });
expect(switchedAgain.agent).toMatchObject({ adapterType: "paperclip_runner", adapterConfig: { provider: "codex", ...savedSettings } });
runnerTarget.platform = "win32";
runnerTarget.architecture = "x64";
const edited = await svc.ensure(companyId, "briefs", { adapterType: "codex_local", adapterConfig: { model: "gpt-5.4" } });
expect(edited.agent).toMatchObject({ adapterType: "paperclip_runner", adapterConfig: { provider: "codex", model: "gpt-5.4" } });
});
it("freezes Codex built-in execution in the reviewed hire through service restart", async () => {
const companyId = await seedCompany({ requireApproval: true });
const result = await builtInAgentService(db).provision(companyId, "briefs", { adapterType: "codex_local", adapterConfig: { model: "gpt-5.4" } }, { requestedByUserId: "board-user" });
expect(result.approval?.payload).toMatchObject({ adapterType: "paperclip_runner", adapterConfig: { provider: "codex", model: "gpt-5.4" } });
runnerTarget.platform = "win32";
runnerTarget.architecture = "x64";
await reconcileBuiltInAgentsOnStartup(db);
await approvalService(db).approve(result.approval!.id, "board-user");
const approved = await builtInAgentService(db).get(companyId, "briefs");
expect(approved.agent?.adapterType).toBe(result.approval!.payload.adapterType);
expect(approved.agent?.adapterConfig).toEqual(result.approval!.payload.adapterConfig);
});
it("records the human who enabled a built-in agent and leaves automatic creation unattributed", async () => {
const enabledCompanyId = await seedCompany({ requireApproval: false });
const automaticCompanyId = await seedCompany({ requireApproval: false });
const builtIns = builtInAgentService(db);
const enabled = await builtIns.provision(enabledCompanyId, "briefs", {}, { requestedByUserId: "board-user" });
const automatic = await builtIns.provision(automaticCompanyId, "briefs");
expect(enabled.state.agent?.createdByUserId).toBe("board-user");
expect(automatic.state.agent?.createdByUserId).toBeNull();
});
it("routes policy-gated built-in provisioning through a pending hire approval", async () => {
const companyId = await seedCompany();
const builtIns = builtInAgentService(db);
const result = await builtIns.provision(companyId, "briefs", {
adapterType: "process",
adapterConfig: { command: "echo safe" },
budgetMonthlyCents: 5000,
}, { requestedByUserId: "board-user" });
expect(result.state).toMatchObject({
status: "pending_approval",
agent: {
companyId,
name: "Briefs Agent",
status: "pending_approval",
adapterType: "process",
adapterConfig: { command: "echo safe" },
budgetMonthlyCents: 5000,
},
});
expect(result.approval).toMatchObject({
companyId,
type: "hire_agent",
status: "pending",
requestedByUserId: "board-user",
requestedByAgentId: null,
payload: {
name: "Briefs Agent",
role: "general",
adapterType: "process",
adapterConfig: { command: "echo safe" },
budgetMonthlyCents: 5000,
agentId: result.state.agentId,
sourceBuiltInAgentKey: "briefs",
featureKeys: ["briefs"],
},
});
const rowsBeforeApproval = await db.select().from(agents).where(eq(agents.companyId, companyId));
expect(rowsBeforeApproval).toHaveLength(1);
expect(rowsBeforeApproval[0]).toMatchObject({ status: "pending_approval", createdByUserId: "board-user" });
await expect(builtIns.requireBuiltInAgent(companyId, "briefs")).rejects.toMatchObject({
status: 412,
details: { code: "built_in_agent_not_configured", status: "pending_approval" },
});
await expect(agentService(db).update(result.state.agentId!, {
adapterType: "process",
adapterConfig: { command: "echo tampered" },
})).rejects.toMatchObject({
status: 409,
details: {
code: "pending_approval_agent_config_frozen",
agentId: result.state.agentId,
fields: ["adapterConfig"],
},
});
await expect(builtIns.provision(companyId, "briefs", {
budgetMonthlyCents: 7500,
})).rejects.toMatchObject({
status: 409,
details: {
code: "built_in_agent_pending_approval",
key: "briefs",
agentId: result.state.agentId,
},
});
await db
.update(agents)
.set({
adapterType: "process",
adapterConfig: { command: "echo tampered" },
})
.where(eq(agents.id, result.state.agentId!));
await approvalService(db).approve(result.approval!.id, "board-user", "Approved built-in agent");
await expect(builtIns.get(companyId, "briefs")).resolves.toMatchObject({
status: "ready",
agentId: result.state.agentId,
agent: { status: "idle", adapterType: "process", adapterConfig: { command: "echo safe" }, budgetMonthlyCents: 5000 },
});
});
it("blocks policy-gated built-in reconfiguration instead of applying adapter overrides immediately", 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 expect(builtIns.provision(companyId, "briefs", {
adapterType: "process",
adapterConfig: { command: "echo bypass" },
})).rejects.toMatchObject({
status: 409,
details: {
code: "built_in_agent_reconfiguration_requires_approval",
key: "briefs",
agentId: ready.agentId,
},
});
await expect(builtIns.get(companyId, "briefs")).resolves.toMatchObject({
status: "ready",
agentId: ready.agentId,
agent: { adapterType: "paperclip_runner", adapterConfig: { provider: "codex", model: "gpt-5.4" } },
});
});
it("completes first-time setup of a needs_setup built-in without a fresh board approval", async () => {
const companyId = await seedCompany({ requireApproval: true });
const builtIns = builtInAgentService(db);
// A hired-but-unconfigured built-in row: exists (its hire was already
// sanctioned) but its adapter config is still empty → `needs_setup`.
const seeded = await builtIns.ensure(companyId, "briefs");
expect(seeded.status).toBe("needs_setup");
// Configuring the adapter for the first time must apply directly instead of
// throwing "adapter changes require board approval".
const result = await builtIns.provision(companyId, "briefs", {
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
budgetMonthlyCents: 2500,
}, { requestedByUserId: "board-user" });
expect(result.approval).toBeNull();
expect(result.state).toMatchObject({
status: "ready",
agentId: seeded.agentId,
agent: {
status: "idle",
adapterType: "paperclip_runner",
adapterConfig: { provider: "codex", model: "gpt-5.4" },
budgetMonthlyCents: 2500,
},
});
const rows = await db.select().from(agents).where(eq(agents.companyId, companyId));
expect(rows).toHaveLength(1);
const noApprovals = await db.select().from(approvals).where(eq(approvals.companyId, companyId));
expect(noApprovals).toHaveLength(0);
});
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("rejects unknown built-in adapter models before saving setup", async () => {
const companyId = await seedCompany();
await expect(builtInAgentService(db).ensure(companyId, "summarizer", {
adapterType: "claude_local",
adapterConfig: { model: "claude-haiku-4-6" },
})).rejects.toMatchObject({
status: 422,
details: {
code: "built_in_agent_model_unknown",
key: "summarizer",
adapterType: "claude_local",
model: "claude-haiku-4-6",
},
});
const rows = await db.select().from(agents).where(eq(agents.companyId, companyId));
expect(rows).toHaveLength(0);
});
it("recovers an orphaned marked row instead of creating a duplicate", async () => {
const companyId = await seedCompany();
const orphanId = randomUUID();
await db.insert(agents).values({
id: orphanId,
companyId,
name: "Old Briefs",
role: "general",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
metadata: withBuiltInAgentMarker({ source: "orphan" }, { key: "briefs", featureKeys: ["briefs"] }),
});
const state = await builtInAgentService(db).ensure(companyId, "briefs");
expect(state.status).toBe("ready");
expect(state.agentId).toBe(orphanId);
const rows = await db.select().from(agents).where(eq(agents.companyId, companyId));
expect(rows).toHaveLength(1);
});
it("derives not_provisioned, needs_setup, ready, and paused states", async () => {
const companyId = await seedCompany();
const builtIns = builtInAgentService(db);
await expect(builtIns.get(companyId, "learning")).resolves.toMatchObject({ status: "not_provisioned" });
const needsSetup = await builtIns.ensure(companyId, "learning");
expect(needsSetup.status).toBe("needs_setup");
expect(deriveBuiltInAgentStatus(needsSetup.agent)).toBe("needs_setup");
const ready = await builtIns.ensure(companyId, "learning", {
adapterType: "claude_local",
adapterConfig: { model: "claude-sonnet-4-5" },
});
expect(ready.status).toBe("ready");
await createAgentLifecycle(db).pauseAgent(ready.agentId!, "manual");
await expect(builtIns.get(companyId, "learning")).resolves.toMatchObject({
status: "paused",
agentId: ready.agentId,
pauseReason: "manual",
});
});
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 createAgentLifecycle(db).pauseAgent(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", {}, instructionOperator);
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: "paperclip_runner",
adapterConfig: { provider: "codex", model: "gpt-5.4" },
},
});
});
it("reconciles an enabled Reflection Coach bundle with skill sync and a disabled routine", async () => {
const companyId = await seedCompany({ requireApproval: false });
const root = await createAgentLifecycle(db).requestHire(companyId, {
name: "CEO",
role: "ceo",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4", apiKey: "do-not-copy" },
runtimeConfig: {},
permissions: {},
});
// The Reflection Coach is opt-in (not auto-created). Enabling it on demand
// materializes its managed bundle in a single pass.
const enabled = await builtInAgentService(db).ensure(companyId, "reflection-coach");
expect(enabled.agent?.adapterConfig).toMatchObject({
instructionsBundleMode: "managed",
instructionsEntryFile: "AGENTS.md",
});
expect(enabled.agent?.adapterConfig).not.toMatchObject({ model: "gpt-5.4", apiKey: "do-not-copy" });
// Startup reconcile keeps the enabled bundle tracking stock and re-grants
// the root/company default permissions.
const result = await reconcileBuiltInAgentsOnStartup(db);
expect(result.autoEnsured).toBeGreaterThanOrEqual(1);
expect(result.defaultGrantsEnsured).toBeGreaterThanOrEqual(4);
const rootGrantKeys = await permissionKeysForAgent(root.id);
expect(rootGrantKeys).toEqual(expect.arrayContaining([
"agents:configure", "agents:suggest-changes", "skills:create", "skills:suggest-changes",
]));
const state = await builtInAgentService(db).get(companyId, "reflection-coach");
expect(state).toMatchObject({
status: "paused",
agent: {
companyId,
name: "Reflection Coach",
role: "general",
title: "Reflection Coach",
icon: "eye",
adapterType: "paperclip_runner",
permissions: {
canCreateAgents: false,
canCreateSkills: false,
},
},
});
expect(state.resources.map((resource) => [resource.resourceKind, resource.stockStatus])).toEqual([
["instructions", "stock_current"],
["skill", "stock_current"],
["routine", "stock_current"],
]);
expect(state.resources.find((resource) => resource.resourceKind === "routine")).toMatchObject({
resourceId: expect.any(String),
scheduleEnabled: false,
});
const agentRows = await db.select().from(agents).where(eq(agents.companyId, companyId));
expect(agentRows.filter((row) => readBuiltInAgentMarker(row.metadata)?.key === "reflection-coach")).toHaveLength(1);
const [skill] = await db
.select()
.from(companySkills)
.where(eq(companySkills.key, "paperclipai/bundled/paperclip-operations/reflection-coach"));
expect(skill).toMatchObject({
key: "paperclipai/bundled/paperclip-operations/reflection-coach",
slug: "reflection-coach",
});
expect(readPaperclipSkillSyncPreference(state.agent!.adapterConfig as Record<string, unknown>).desiredSkills).toContain(
"paperclipai/bundled/paperclip-operations/reflection-coach",
);
const [routine] = await db.select().from(routines).where(eq(routines.companyId, companyId));
expect(routine).toMatchObject({
title: "Review recent agent trajectories for coaching proposals",
status: "paused",
assigneeAgentId: state.agentId,
});
const [trigger] = await db.select().from(routineTriggers).where(eq(routineTriggers.routineId, routine!.id));
expect(trigger).toMatchObject({
kind: "schedule",
enabled: false,
cronExpression: "0 9 * * 1",
timezone: "UTC",
});
const coachGrantKeys = await permissionKeysForAgent(state.agentId!);
expect(coachGrantKeys).toEqual(expect.arrayContaining(["agents:suggest-changes", "skills:suggest-changes"]));
expect(coachGrantKeys).not.toContain("agents:configure");
expect(coachGrantKeys).not.toContain("skills:create");
});
it("recreates missing managed resource bindings idempotently during concurrent reconcile", async () => {
const companyId = await seedCompany({ requireApproval: false });
await createAgentLifecycle(db).requestHire(companyId, {
name: "CEO",
role: "ceo",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
});
const builtIns = builtInAgentService(db);
await builtIns.ensure(companyId, "reflection-coach");
await db.delete(builtInManagedResources).where(eq(builtInManagedResources.companyId, companyId));
const states = await Promise.all([
builtIns.ensure(companyId, "reflection-coach"),
builtIns.ensure(companyId, "reflection-coach"),
]);
expect(states).toHaveLength(2);
for (const state of states) {
expect(state.resources.map((resource) => [resource.resourceKind, resource.stockStatus])).toEqual([
["instructions", "stock_current"],
["skill", "stock_current"],
["routine", "stock_current"],
]);
}
const bindings = await db
.select()
.from(builtInManagedResources)
.where(eq(builtInManagedResources.companyId, companyId));
expect(bindings).toHaveLength(3);
expect(new Set(bindings.map((binding) =>
`${binding.bundleKey}:${binding.resourceKind}:${binding.resourceKey}`
)).size).toBe(3);
});
it("preserves new-agent approval gates during on-demand Reflection Coach provisioning", async () => {
const companyId = await seedCompany({ requireApproval: true });
const root = await createAgentLifecycle(db).requestHire(companyId, {
name: "CEO",
role: "ceo",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
});
const mutationPolicy = {
requiresDisplayedDiff: true,
requiresAcceptedTaskInteraction: true,
applyInSeparateFollowUpRun: true,
};
// The Reflection Coach is opt-in, so it's enabled on demand. With board
// approval required, provisioning it must leave a pending agent + a
// hire_agent approval rather than an active agent.
const provisioned = await builtInAgentService(db).provision(companyId, "reflection-coach");
expect(provisioned.approval).not.toBeNull();
const state = await builtInAgentService(db).get(companyId, "reflection-coach");
expect(state).toMatchObject({
status: "pending_approval",
agent: {
companyId,
name: "Reflection Coach",
status: "pending_approval",
reportsTo: root.id,
budgetMonthlyCents: 0,
permissions: {
builtInMutationPolicy: mutationPolicy,
},
},
});
expect(state.resources.map((resource) => resource.stockStatus)).toEqual(["missing", "missing", "missing"]);
const allApprovals = await db.select().from(approvals).where(eq(approvals.companyId, companyId));
const approval = allApprovals.find(
(row) => (row.payload as { agentId?: string } | null)?.agentId === state.agentId,
)!;
expect(approval).toMatchObject({
type: "hire_agent",
status: "pending",
payload: {
agentId: state.agentId,
sourceBuiltInAgentKey: "reflection-coach",
featureKeys: ["reflection-coach"],
reportsTo: root.id,
permissions: expect.objectContaining({
builtInMutationPolicy: mutationPolicy,
}),
},
});
const pendingReconcile = await reconcileBuiltInAgentsOnStartup(db);
expect(pendingReconcile.pendingApprovals).toBe(1);
const stillPending = await builtInAgentService(db).get(companyId, "reflection-coach");
expect(stillPending).toMatchObject({
status: "pending_approval",
agent: {
adapterConfig: {},
reportsTo: root.id,
status: "pending_approval",
},
});
expect(stillPending.resources.map((resource) => resource.stockStatus)).toEqual([
"missing",
"missing",
"missing",
]);
await approvalService(db).approve(approval.id, "board-user", "Approved Reflection Coach");
const approvedState = await builtInAgentService(db).get(companyId, "reflection-coach");
expect(approvedState).toMatchObject({
agent: {
reportsTo: root.id,
permissions: {
builtInMutationPolicy: mutationPolicy,
},
},
});
expect(approvedState.resources.map((resource) => resource.stockStatus)).toEqual([
"stock_current",
"stock_current",
"stock_current",
]);
await reconcileBuiltInAgentsOnStartup(db);
const agentRows = await db.select().from(agents).where(eq(agents.companyId, companyId));
expect(agentRows.filter((row) => readBuiltInAgentMarker(row.metadata)?.key === "reflection-coach")).toHaveLength(1);
const approvalRows = await db.select().from(approvals).where(eq(approvals.companyId, companyId));
expect(approvalRows).toHaveLength(1);
});
it("automatically upgrades untouched stock instructions while preserving personal files", async () => {
const companyId = await seedCompany({ requireApproval: false });
const svc = builtInAgentService(db);
const created = await svc.ensure(companyId, "reflection-coach");
const agent = created.agent!;
const oldFiles = { "AGENTS.md": "# Previous stock instructions\n", "obsolete.txt": "old stock support" };
await writeInstructionEntry(agent, "AGENTS.md", oldFiles["AGENTS.md"]);
await agentInstructionsService(db).writeFile(agent, "obsolete.txt", oldFiles["obsolete.txt"]);
await agentInstructionsService(db).writeFile(agent, "personal.txt", "keep my notes");
await db.update(builtInManagedResources).set({ stockHash: stockHash(oldFiles), stockVersion: "previous",
defaultsJson: { entryFile: "AGENTS.md", files: Object.keys(oldFiles) },
}).where(and(eq(builtInManagedResources.companyId, companyId), eq(builtInManagedResources.resourceKind, "instructions")));
const updated = await svc.ensure(companyId, "reflection-coach");
expect(updated.resources.find(resource => resource.resourceKind === "instructions")).toMatchObject({ stockStatus: "stock_current" });
expect((await agentInstructionsService().readFile(updated.agent!, "AGENTS.md")).content).toContain("You are Reflection Coach");
expect((await agentInstructionsService().readFile(updated.agent!, "personal.txt")).content).toBe("keep my notes");
await expect(agentInstructionsService().readFile(updated.agent!, "obsolete.txt")).rejects.toMatchObject({ status: 404 });
const [event] = await db.select().from(activityLog).where(and(eq(activityLog.companyId, companyId), eq(activityLog.actorId, "built-in-reconcile")));
expect(event).toMatchObject({ actorType: "system", action: "agent.files_updated" });
});
it.each(["file", "database"])("retries a stock update after a %s failure without overwriting intervening edits", async (failure) => {
const companyId = await seedCompany({ requireApproval: false });
const svc = builtInAgentService(db);
const created = await svc.ensure(companyId, "reflection-coach");
const agent = created.agent!;
const oldFiles = { "AGENTS.md": "# Old stock\n", "obsolete.txt": "old supporting file" };
await writeInstructionEntry(agent, "AGENTS.md", oldFiles["AGENTS.md"]);
await agentInstructionsService(db).writeFile(agent, "obsolete.txt", oldFiles["obsolete.txt"]);
await db.update(builtInManagedResources).set({ stockHash: stockHash(oldFiles), stockVersion: "old",
defaultsJson: { entryFile: "AGENTS.md", files: Object.keys(oldFiles) },
}).where(and(eq(builtInManagedResources.companyId, companyId), eq(builtInManagedResources.resourceKind, "instructions")));
const trigger = `stock_failure_${companyId.replaceAll("-", "")}`;
const remove = fs.rm.bind(fs);
const fault = failure === "file" ? vi.spyOn(fs, "rm").mockImplementation(async (file, options) => {
if (String(file).endsWith("/obsolete.txt")) throw new Error("injected stock file failure");
return remove(file, options);
}) : null;
if (failure === "database") {
await db.execute(sql.raw(`CREATE FUNCTION ${trigger}() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN
IF NEW.company_id = '${companyId}' AND NEW.resource_kind = 'instructions' AND NEW.stock_hash <> OLD.stock_hash THEN
RAISE EXCEPTION 'injected stock binding failure'; END IF; RETURN NEW; END $$`));
await db.execute(sql.raw(`CREATE TRIGGER ${trigger} BEFORE UPDATE ON built_in_managed_resources FOR EACH ROW EXECUTE FUNCTION ${trigger}()`));
}
try { await expect(svc.ensure(companyId, "reflection-coach")).rejects.toThrow(); }
finally {
fault?.mockRestore();
if (failure === "database") {
await db.execute(sql.raw(`DROP TRIGGER ${trigger} ON built_in_managed_resources`));
await db.execute(sql.raw(`DROP FUNCTION ${trigger}()`));
}
}
const [pending] = await db.select().from(builtInManagedResources).where(and(eq(builtInManagedResources.companyId, companyId), eq(builtInManagedResources.resourceKind, "instructions")));
expect(pending.defaultsJson.pendingInstructionsUpdate).toBeTruthy();
expect(pending.stockHash).toBe(stockHash(oldFiles));
const partial = (await agentInstructionsService().readFile(agent, "AGENTS.md")).content;
expect(partial).toContain("You are Reflection Coach");
// A real operator edit after the failed attempt must stop the retry.
await writeInstructionEntry(agent, "AGENTS.md", "operator edit after failure");
await svc.ensure(companyId, "reflection-coach");
expect((await agentInstructionsService().readFile(agent, "AGENTS.md")).content).toBe("operator edit after failure");
await writeInstructionEntry(agent, "AGENTS.md", partial);
const retried = await svc.ensure(companyId, "reflection-coach");
expect(retried.resources.find(resource => resource.resourceKind === "instructions")).toMatchObject({ stockStatus: "stock_current" });
await expect(agentInstructionsService().readFile(agent, "obsolete.txt")).rejects.toMatchObject({ status: 404 });
const [complete] = await db.select().from(builtInManagedResources).where(eq(builtInManagedResources.id, pending.id));
expect(complete.defaultsJson.pendingInstructionsUpdate).toBeUndefined();
});
it.each([false, true])("supersedes an interrupted stock version, including rollback=%s", async (rollback) => {
const companyId = await seedCompany({ requireApproval: false });
const svc = builtInAgentService(db);
const created = await svc.ensure(companyId, "reflection-coach");
const agent = created.agent!;
const currentStock = (await agentInstructionsService().readFile(agent, "AGENTS.md")).content;
const oldFiles = { "AGENTS.md": rollback ? currentStock : "# Original stock" };
const interruptedFiles = { "AGENTS.md": "# Intermediate stock", "intermediate-only.txt": "intermediate support" };
await writeInstructionEntry(agent, "AGENTS.md", interruptedFiles["AGENTS.md"]);
await agentInstructionsService(db).writeFile(agent, "intermediate-only.txt", interruptedFiles["intermediate-only.txt"]);
await agentInstructionsService(db).writeFile(agent, "personal.txt", "personal notes");
await db.update(builtInManagedResources).set({ stockHash: stockHash(oldFiles), stockVersion: "old",
defaultsJson: { entryFile: "AGENTS.md", files: Object.keys(oldFiles), pendingInstructionsUpdate: {
stockHash: stockHash(interruptedFiles),
baseHashes: { "AGENTS.md": fileHash(Buffer.from(oldFiles["AGENTS.md"])), "intermediate-only.txt": null },
nextHashes: Object.fromEntries(Object.entries(interruptedFiles).map(([file, text]) => [file, fileHash(Buffer.from(text))])),
} },
}).where(and(eq(builtInManagedResources.companyId, companyId), eq(builtInManagedResources.resourceKind, "instructions")));
await writeInstructionEntry(agent, "AGENTS.md", "intervening operator edit");
await svc.ensure(companyId, "reflection-coach");
expect((await agentInstructionsService().readFile(agent, "AGENTS.md")).content).toBe("intervening operator edit");
await writeInstructionEntry(agent, "AGENTS.md", interruptedFiles["AGENTS.md"]);
const updated = await svc.ensure(companyId, "reflection-coach");
expect(updated.resources.find(resource => resource.resourceKind === "instructions")).toMatchObject({ stockStatus: "stock_current" });
expect((await agentInstructionsService().readFile(agent, "AGENTS.md")).content).toBe(currentStock);
await expect(agentInstructionsService().readFile(agent, "intermediate-only.txt")).rejects.toMatchObject({ status: 404 });
expect((await agentInstructionsService().readFile(agent, "personal.txt")).content).toBe("personal notes");
});
it("preserves Reflection Coach instruction drift on reconcile and restores it on reset", async () => {
const companyId = await seedCompany();
const builtIns = builtInAgentService(db);
const created = await builtIns.ensure(companyId, "reflection-coach");
const instructions = agentInstructionsService();
await writeInstructionEntry(created.agent!, "AGENTS.md", "# Custom Reflection Coach\n\nOperator edit.\n");
const reconciled = await builtIns.ensure(companyId, "reflection-coach");
const drift = reconciled.resources.find((resource) => resource.resourceKind === "instructions");
expect(drift).toMatchObject({
stockStatus: "operator_modified",
updateAvailable: true,
resetAvailable: true,
changedFiles: ["AGENTS.md"],
});
await expect(instructions.readFile(reconciled.agent!, "AGENTS.md")).resolves.toMatchObject({
content: "# Custom Reflection Coach\n\nOperator edit.\n",
});
const reset = await builtIns.reset(companyId, "reflection-coach", {}, instructionOperator);
expect(reset.resources.find((resource) => resource.resourceKind === "instructions")).toMatchObject({
stockStatus: "stock_current",
resetAvailable: false,
});
const resetFile = await instructions.readFile(reset.agent!, "AGENTS.md");
expect(resetFile.content).toContain("Reflection Coach");
expect(resetFile.content).not.toContain("Operator edit.");
const revisions = agentInstructionRevisionService(db);
const target = { companyId, agentId: created.agent!.id, entryFile: "AGENTS.md" };
const history = await revisions.history(target, instructionOperator);
expect(history.revisions).toHaveLength(0);
const current = await revisions.readCurrent(target, instructionOperator);
expect(current?.content).toBe(resetFile.content);
});
it("blocks deleting a built-in agent", async () => {
const companyId = await seedCompany();
const state = await builtInAgentService(db).ensure(companyId, "briefs");
await expect(agentService(db).remove(state.agentId!)).rejects.toMatchObject({
status: 409,
details: {
code: "built_in_agent_undeletable",
key: "briefs",
},
});
});
it("prevents direct marker add, remove, or mutation", async () => {
const companyId = await seedCompany();
const builtIn = await builtInAgentService(db).ensure(companyId, "briefs");
const normal = await createAgentLifecycle(db).requestHire(companyId, {
name: "Normal",
role: "engineer",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
});
await expect(createAgentLifecycle(db).requestHire(companyId, {
name: "Spoof",
role: "engineer",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
metadata: withBuiltInAgentMarker({}, { key: "briefs", featureKeys: ["briefs"] }),
})).rejects.toMatchObject({ status: 409, details: { code: "built_in_agent_marker_readonly" } });
await expect(agentService(db).update(normal.id, {
metadata: withBuiltInAgentMarker({}, { key: "briefs", featureKeys: ["briefs"] }),
})).rejects.toMatchObject({ status: 409, details: { code: "built_in_agent_marker_readonly" } });
await expect(agentService(db).update(builtIn.agentId!, {
metadata: { other: "metadata" },
})).rejects.toMatchObject({ status: 409, details: { code: "built_in_agent_marker_readonly" } });
await expect(agentService(db).update(builtIn.agentId!, {
metadata: withBuiltInAgentMarker({}, { key: "learning", featureKeys: ["learning"] }),
})).rejects.toMatchObject({ status: 409, details: { code: "built_in_agent_marker_readonly" } });
await expect(agentService(db).update(builtIn.agentId!, {
metadata: withBuiltInAgentMarker({ note: "allowed" }, { key: "briefs", featureKeys: ["briefs"] }),
})).resolves.toMatchObject({
id: builtIn.agentId,
metadata: {
note: "allowed",
paperclipBuiltInAgent: { key: "briefs", featureKeys: ["briefs"] },
},
});
});
it("repairs display/default drift for marked rows during startup reconciliation", async () => {
const companyId = await seedCompany();
const agentId = randomUUID();
await db.insert(agents).values({
id: agentId,
companyId,
name: "Old Name",
role: "engineer",
title: "Old title",
capabilities: "Old purpose",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
metadata: withBuiltInAgentMarker({}, { key: "briefs", featureKeys: ["old-briefs"] }),
});
const result = await reconcileBuiltInAgentsOnStartup(db);
expect(result).toMatchObject({ unknown: 0, duplicates: 0 });
expect(result.scanned).toBeGreaterThanOrEqual(1);
expect(result.reconciled).toBeGreaterThanOrEqual(1);
const [row] = await db.select().from(agents).where(eq(agents.id, agentId));
expect(row).toMatchObject({
name: "Briefs Agent",
role: "general",
title: null,
capabilities: "Prepares concise operational briefs for the board and agent company.",
});
expect(readBuiltInAgentMarker(row?.metadata)).toEqual({ key: "briefs", featureKeys: ["briefs"] });
});
// Reproduce a company that already carries duplicate marked rows from before
// migration 0192 by dropping the unique index, inserting two active rows, and
// pairing a pending hire_agent approval with the newer one.
async function seedLegacyDuplicateBriefs(companyId: string) {
await db.execute(sql.raw(`DROP INDEX IF EXISTS "${BUILT_IN_MARKER_UNIQUE_INDEX}"`));
const olderId = randomUUID();
const newerId = randomUUID();
await db.insert(agents).values([
{
id: olderId,
companyId,
name: "Briefs One",
role: "general",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
createdAt: new Date("2026-07-18T00:00:00.000Z"),
metadata: withBuiltInAgentMarker({}, { key: "briefs", featureKeys: ["briefs"] }),
},
{
id: newerId,
companyId,
name: "Briefs Two",
role: "general",
status: "pending_approval",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
createdAt: new Date("2026-07-18T00:00:00.025Z"),
metadata: withBuiltInAgentMarker({}, { key: "briefs", featureKeys: ["briefs"] }),
},
]);
const approval = await approvalService(db).create(companyId, {
type: "hire_agent",
requestedByAgentId: null,
requestedByUserId: null,
status: "pending",
payload: { agentId: newerId, sourceBuiltInAgentKey: "briefs", featureKeys: ["briefs"] },
decisionNote: null,
decidedByUserId: null,
decidedAt: null,
updatedAt: new Date(),
});
return { olderId, newerId, approvalId: approval!.id };
}
it("self-heals duplicate active instances, keeping the oldest and cancelling the newer's approval", async () => {
const companyId = await seedCompany();
const { olderId, newerId, approvalId } = await seedLegacyDuplicateBriefs(companyId);
// A plain read resolves the duplicate rather than throwing.
const state = await builtInAgentService(db).get(companyId, "briefs");
expect(state.agentId).toBe(olderId);
const rows = await db.select().from(agents).where(eq(agents.companyId, companyId));
const byId = new Map(rows.map((row) => [row.id, row]));
expect(byId.get(olderId)?.status).toBe("idle");
expect(byId.get(newerId)?.status).toBe("terminated");
expect(
rows.filter((row) => row.status !== "terminated" && readBuiltInAgentMarker(row.metadata)?.key === "briefs"),
).toHaveLength(1);
const [approval] = await db.select().from(approvals).where(eq(approvals.id, approvalId));
expect(approval?.status).toBe("cancelled");
});
it("makes concurrent provisioning lose cleanly instead of creating duplicates", async () => {
const companyId = await seedCompany({ requireApproval: false });
const svc = builtInAgentService(db);
const [first, second] = await Promise.all([
svc.ensure(companyId, "briefs"),
svc.ensure(companyId, "briefs"),
]);
expect(first.agentId).toBeTruthy();
expect(second.agentId).toBe(first.agentId);
const rows = await db.select().from(agents).where(eq(agents.companyId, companyId));
expect(
rows.filter((row) => row.status !== "terminated" && readBuiltInAgentMarker(row.metadata)?.key === "briefs"),
).toHaveLength(1);
// The partial unique index now rejects any further active marked row.
await expect(
db.insert(agents).values({
id: randomUUID(),
companyId,
name: "Briefs Dupe",
role: "general",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
metadata: withBuiltInAgentMarker({}, { key: "briefs", featureKeys: ["briefs"] }),
}),
).rejects.toMatchObject({
cause: {
code: "23505",
constraint_name: BUILT_IN_MARKER_UNIQUE_INDEX,
},
});
});
it("makes concurrent board-gated provisioning resolve to a single pending agent and approval", async () => {
const companyId = await seedCompany({ requireApproval: true });
const svc = builtInAgentService(db);
const results = await Promise.all([
svc.provision(companyId, "briefs"),
svc.provision(companyId, "briefs"),
]);
const agentIds = new Set(results.map((result) => result.state.agentId));
expect(agentIds.size).toBe(1);
const rows = await db.select().from(agents).where(eq(agents.companyId, companyId));
expect(
rows.filter((row) => row.status !== "terminated" && readBuiltInAgentMarker(row.metadata)?.key === "briefs"),
).toHaveLength(1);
const openApprovals = await db
.select()
.from(approvals)
.where(and(eq(approvals.companyId, companyId), eq(approvals.status, "pending")));
const briefsApprovals = openApprovals.filter(
(row) => (row.payload as { sourceBuiltInAgentKey?: string } | null)?.sourceBuiltInAgentKey === "briefs",
);
expect(briefsApprovals).toHaveLength(1);
// The winner returns its freshly created approval; the loser returns the
// same approval or null (if it re-resolves before that row commits), never
// a second one.
expect(results.some((result) => result.approval?.id === briefsApprovals[0]!.id)).toBe(true);
for (const result of results) {
if (result.approval) {
expect(result.approval.id).toBe(briefsApprovals[0]!.id);
}
}
});
it("self-heals duplicates during startup reconciliation without aborting later companies", async () => {
const affectedCompanyId = await seedCompany({ requireApproval: false });
const { olderId, newerId } = await seedLegacyDuplicateBriefs(affectedCompanyId);
// A second company created after the affected one — previously skipped
// entirely because the duplicate error escaped the reconciliation loop.
// Give it a drifted built-in row so we can prove reconcile still reached it.
const healthyCompanyId = await seedCompany({ requireApproval: false });
const healthyBriefsId = randomUUID();
await db.insert(agents).values({
id: healthyBriefsId,
companyId: healthyCompanyId,
name: "Stale Briefs",
role: "engineer",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
metadata: withBuiltInAgentMarker({}, { key: "briefs", featureKeys: ["briefs"] }),
});
const result = await reconcileBuiltInAgentsOnStartup(db);
expect(result.companyFailures).toBe(0);
const affectedRows = await db.select().from(agents).where(eq(agents.companyId, affectedCompanyId));
const affectedById = new Map(affectedRows.map((row) => [row.id, row]));
expect(affectedById.get(olderId)?.status).toBe("idle");
expect(affectedById.get(newerId)?.status).toBe("terminated");
expect(
affectedRows.filter(
(row) => row.status !== "terminated" && readBuiltInAgentMarker(row.metadata)?.key === "briefs",
),
).toHaveLength(1);
// The company after the affected one was still reconciled (its drifted
// built-in row was repaired to stock) rather than skipped.
const [healthyBriefs] = await db.select().from(agents).where(eq(agents.id, healthyBriefsId));
expect(healthyBriefs?.name).toBe("Briefs Agent");
});
it("automatically materializes the Reflection Coach bundle without enabling background work", async () => {
const companyId = await seedCompany();
const root = await createAgentLifecycle(db).requestHire(companyId, {
name: "CEO",
role: "ceo",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
});
const state = await builtInAgentService(db).ensure(companyId, "reflection-coach");
expect(state.agent).toMatchObject({
companyId,
name: "Reflection Coach",
title: "Reflection Coach",
icon: "eye",
reportsTo: root.id,
adapterType: "paperclip_runner",
budgetMonthlyCents: 0,
});
expect(state.status).toBe("paused");
expect(readBuiltInAgentMarker(state.agent?.metadata)).toEqual({
key: "reflection-coach",
featureKeys: ["reflection-coach"],
});
expect(state.resources.map((resource) => [resource.resourceKind, resource.stockStatus])).toEqual([
["instructions", "stock_current"],
["skill", "stock_current"],
["routine", "stock_current"],
]);
const reported = await builtInAgentService(db).get(companyId, "reflection-coach");
const reportedRoutine = reported.resources.find((resource) => resource.resourceKind === "routine");
expect(reportedRoutine).toMatchObject({
stockStatus: "stock_current",
updateAvailable: false,
resetAvailable: false,
});
expect(reportedRoutine?.currentHash).toBe(reportedRoutine?.stockHash);
const [skill] = await db
.select()
.from(companySkills)
.where(eq(companySkills.key, "paperclipai/bundled/paperclip-operations/reflection-coach"));
expect(skill).toMatchObject({
key: "paperclipai/bundled/paperclip-operations/reflection-coach",
slug: "reflection-coach",
});
expect(readPaperclipSkillSyncPreference(state.agent!.adapterConfig).desiredSkills).toContain(skill!.key);
const [routine] = await db.select().from(routines).where(eq(routines.companyId, companyId));
expect(routine).toMatchObject({
title: "Review recent agent trajectories for coaching proposals",
status: "paused",
assigneeAgentId: state.agentId,
originKind: "built_in_agent_bundle",
originId: "reflection-coach:recent-agent-reflection",
});
const [trigger] = await db.select().from(routineTriggers).where(eq(routineTriggers.routineId, routine!.id));
expect(trigger).toMatchObject({
kind: "schedule",
enabled: false,
cronExpression: "0 9 * * 1",
timezone: "UTC",
});
const grantKeys = await permissionKeysForAgent(state.agentId!);
expect(grantKeys).toEqual(expect.arrayContaining(["agents:suggest-changes", "skills:suggest-changes"]));
expect(grantKeys).not.toContain("tasks:assign");
expect(grantKeys).not.toContain("agents:configure");
expect(grantKeys).not.toContain("skills:create");
});
it("materializes the Summarizer bundle paused on Claude Haiku with a disabled routine", async () => {
const companyId = await seedCompany();
const root = await createAgentLifecycle(db).requestHire(companyId, {
name: "CEO",
role: "ceo",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
});
const state = await builtInAgentService(db).ensure(companyId, "summarizer");
expect(state.agent).toMatchObject({
companyId,
name: "Summarizer",
title: "Summarizer",
icon: "sparkles",
role: "general",
reportsTo: root.id,
adapterType: "paperclip_runner",
adapterConfig: { provider: "acpx", acpxAgent: "claude", model: "claude-haiku-4-5" },
budgetMonthlyCents: 0,
});
expect(state.status).toBe("paused");
expect(state.pauseReason).toBe("Built-in Summarizer is disabled until explicitly configured.");
expect(readBuiltInAgentMarker(state.agent?.metadata)).toEqual({
key: "summarizer",
featureKeys: ["summarizer"],
});
expect(state.resources.map((resource) => [resource.resourceKind, resource.stockStatus])).toEqual([
["instructions", "stock_current"],
["skill", "stock_current"],
["routine", "stock_current"],
]);
const [skill] = await db
.select()
.from(companySkills)
.where(eq(companySkills.key, "paperclipai/bundled/paperclip-operations/summarize-status"));
expect(skill).toMatchObject({
key: "paperclipai/bundled/paperclip-operations/summarize-status",
slug: "summarize-status",
});
expect(readPaperclipSkillSyncPreference(state.agent!.adapterConfig).desiredSkills).toContain(skill!.key);
const [routine] = await db
.select()
.from(routines)
.where(and(eq(routines.companyId, companyId), eq(routines.assigneeAgentId, state.agentId!)));
expect(routine).toMatchObject({
title: "Refresh stale summary slots",
status: "paused",
assigneeAgentId: state.agentId,
originKind: "built_in_agent_bundle",
originId: "summarizer:refresh-stale-summaries",
});
const [trigger] = await db.select().from(routineTriggers).where(eq(routineTriggers.routineId, routine!.id));
expect(trigger).toMatchObject({
kind: "schedule",
enabled: false,
cronExpression: "0 8 * * *",
timezone: "UTC",
});
});
it("keeps the Summarizer not-configured until an adapter model is set", async () => {
const companyId = await seedCompany();
await expect(builtInAgentService(db).requireBuiltInAgent(companyId, "summarizer")).rejects.toMatchObject({
status: 412,
details: {
code: "built_in_agent_not_configured",
key: "summarizer",
},
});
// Provisioning without a model leaves it paused (default), still not runnable as "ready".
const paused = await builtInAgentService(db).ensure(companyId, "summarizer");
expect(paused.status).toBe("paused");
await expect(builtInAgentService(db).requireBuiltInAgent(companyId, "summarizer")).resolves.toMatchObject({
warning: { code: "built_in_agent_paused", key: "summarizer" },
});
});
it("restores Summarizer instruction drift on reset", async () => {
const companyId = await seedCompany();
const builtIns = builtInAgentService(db);
const created = await builtIns.ensure(companyId, "summarizer");
const instructions = agentInstructionsService();
await writeInstructionEntry(created.agent!, "AGENTS.md", "# Custom Summarizer\n\nOperator edit.\n");
const reconciled = await builtIns.ensure(companyId, "summarizer");
expect(reconciled.resources.find((resource) => resource.resourceKind === "instructions")).toMatchObject({
stockStatus: "operator_modified",
resetAvailable: true,
changedFiles: ["AGENTS.md"],
});
const reset = await builtIns.reset(companyId, "summarizer", {}, instructionOperator);
expect(reset.resources.find((resource) => resource.resourceKind === "instructions")).toMatchObject({
stockStatus: "stock_current",
resetAvailable: false,
});
const resetFile = await instructions.readFile(reset.agent!, "AGENTS.md");
expect(resetFile.content).toContain("Summarizer");
expect(resetFile.content).toContain("<<<SUMMARY-DRAFT>>>");
expect(resetFile.content).toContain("<<<END-SUMMARY-DRAFT>>>");
expect(resetFile.content).not.toContain("Operator edit.");
});
it("keeps a built-in routine task while the agent prepares", async () => {
const companyId = await seedCompany({ requireApproval: false });
const builtIns = createBuiltInAgentService(db);
const created = await builtIns.ensure(companyId, "reflection-coach");
await lifecycleWorker.stop();
lifecycleWorker = configureAgentLifecycle(db, { requiredPluginIds: async () => [], runPlugin: async () => "complete", runHost: async () => "pending" });
try {
const result = await builtIns.runRoutine(companyId, "reflection-coach", "recent-agent-reflection", { userId: "responsible-user" });
expect(result.status).toBe("issue_created");
const tasks = await db.select().from(issues).where(eq(issues.companyId, companyId));
expect(tasks).toHaveLength(1);
expect(tasks[0]!.assigneeAgentId).toBe(created.agentId);
expect(await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.companyId, companyId)))
.toEqual([expect.objectContaining({ status: "queued", agentId: created.agentId })]);
// A second request during setup must not try to resume an already preparing agent.
await expect(builtIns.runRoutine(companyId, "reflection-coach", "recent-agent-reflection", { userId: "responsible-user" }))
.resolves.toHaveProperty("id");
} finally {
await lifecycleWorker.stop();
await db.delete(routineRuns).where(eq(routineRuns.companyId, companyId));
await db.delete(heartbeatRuns).where(eq(heartbeatRuns.companyId, companyId));
await db.delete(agentWakeupRequests).where(eq(agentWakeupRequests.companyId, companyId));
lifecycleWorker = configureAgentLifecycle(db, { requiredPluginIds: async () => [], runPlugin: async () => "complete", runHost: async () => "complete" });
}
});
it("controls the Reflection Coach routine schedule without enabling it by default", async () => {
const companyId = await seedCompany();
await createAgentLifecycle(db).requestHire(companyId, {
name: "CEO",
role: "ceo",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
});
const builtIns = builtInAgentService(db);
const created = await builtIns.ensure(companyId, "reflection-coach");
expect(created.status).toBe("paused");
expect(created.resources.find((resource) => resource.resourceKind === "routine")).toMatchObject({
stockStatus: "stock_current",
scheduleEnabled: false,
});
const enabled = await builtIns.enableRoutineSchedule(
companyId,
"reflection-coach",
"recent-agent-reflection",
{ userId: "board-user" },
);
await lifecycleWorker.process(enabled.agentId!);
expect((await builtIns.get(companyId, "reflection-coach")).status).toBe("needs_setup");
expect(enabled.resources.find((resource) => resource.resourceKind === "routine")).toMatchObject({
stockStatus: "stock_current",
scheduleEnabled: true,
});
const [enabledRoutine] = await db.select().from(routines).where(eq(routines.companyId, companyId));
const [enabledTrigger] = await db.select().from(routineTriggers).where(eq(routineTriggers.routineId, enabledRoutine!.id));
expect(enabledRoutine).toMatchObject({ status: "active" });
expect(enabledTrigger).toMatchObject({ enabled: true });
const disabled = await builtIns.disableRoutineSchedule(
companyId,
"reflection-coach",
"recent-agent-reflection",
{ userId: "board-user" },
);
expect(disabled.resources.find((resource) => resource.resourceKind === "routine")).toMatchObject({
stockStatus: "stock_current",
scheduleEnabled: false,
});
const [disabledRoutine] = await db.select().from(routines).where(eq(routines.id, enabledRoutine!.id));
const [disabledTrigger] = await db.select().from(routineTriggers).where(eq(routineTriggers.id, enabledTrigger!.id));
expect(disabledRoutine).toMatchObject({ status: "paused" });
expect(disabledTrigger).toMatchObject({ enabled: false });
});
it("surfaces pending Reflection Coach proposal interactions on the routine resource", async () => {
const companyId = await seedCompany();
await createAgentLifecycle(db).requestHire(companyId, {
name: "CEO",
role: "ceo",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
});
const created = await builtInAgentService(db).ensure(companyId, "reflection-coach");
const proposalIssueId = randomUUID();
await db.insert(issues).values({
id: proposalIssueId,
companyId,
title: "Review Reflection Coach proposal",
status: "in_review",
priority: "medium",
identifier: `${issuePrefix(companyId)}-42`,
issueNumber: 42,
assigneeAgentId: created.agentId,
createdByAgentId: created.agentId,
});
const interactionId = randomUUID();
await db.insert(issueThreadInteractions).values({
id: interactionId,
companyId,
issueId: proposalIssueId,
kind: "request_confirmation",
status: "pending",
continuationPolicy: "wake_assignee",
title: "Review proposed coaching change",
summary: "Accept or reject the proposed update.",
createdByAgentId: created.agentId,
payload: {
version: 1,
prompt: "Accept the proposed coaching change?",
acceptLabel: "Accept",
rejectLabel: "Reject",
},
});
const state = await builtInAgentService(db).get(companyId, "reflection-coach");
expect(state.resources.find((resource) => resource.resourceKind === "routine")).toMatchObject({
pendingUpdateInteractionId: interactionId,
pendingUpdateIssueId: proposalIssueId,
pendingUpdateIssueIdentifier: `${issuePrefix(companyId)}-42`,
});
});
it("gates Reflection Coach proposal mutations until an accepted follow-up apply step", async () => {
const companyId = await seedCompany();
const agentsSvc = agentService(db);
const agentsSvcLifecycle = createAgentLifecycle(db);
await agentsSvcLifecycle.requestHire(companyId, {
name: "CEO",
role: "ceo",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
});
const target = await agentsSvcLifecycle.requestHire(companyId, {
name: "Target Coder",
role: "engineer",
status: "idle",
adapterType: "codex_local",
adapterConfig: { model: "gpt-5.4" },
runtimeConfig: {},
permissions: {},
});
const created = await builtInAgentService(db).ensure(companyId, "reflection-coach");
const coach = created.agent!;
const instructionsSvc = agentInstructionsService();
const originalInstructions = "# Target Coder\n\nWork from the assigned issue.\n";
const prepared = await writeInstructionEntry(target, "AGENTS.md", originalInstructions);
let persistedTarget = (await agentsSvc.update(target.id, { adapterConfig: prepared.adapterConfig }))!;
const interactionsSvc = issueThreadInteractionService(db);
const applyAcceptedProposalFollowUp = async (input: {
interactionId: string;
nextInstructions: string;
}) => {
const interaction = await interactionsSvc.getById(input.interactionId);
if (interaction?.kind !== "request_confirmation" || interaction.status !== "accepted") {
return false;
}
const written = await writeInstructionEntry(persistedTarget, "AGENTS.md", input.nextInstructions);
persistedTarget = (await agentsSvc.update(persistedTarget.id, { adapterConfig: written.adapterConfig }))!;
return true;
};
const readTargetInstructions = async () =>
(await instructionsSvc.readFile(persistedTarget, "AGENTS.md")).content;
const proposalIssueId = randomUUID();
await db.insert(issues).values({
id: proposalIssueId,
companyId,
title: "Review Reflection Coach proposal",
status: "in_review",
priority: "medium",
identifier: `${issuePrefix(companyId)}-43`,
issueNumber: 43,
assigneeUserId: "board-user",
createdByAgentId: coach.id,
});
const acceptedInstructions = `${originalInstructions}\nWhen finishing, name the exact verification command.\n`;
const acceptedProposal = await interactionsSvc.create({
id: proposalIssueId,
companyId,
}, {
kind: "request_confirmation",
continuationPolicy: "wake_assignee_on_accept",
title: "Review proposed coaching change",
summary: "Accept or reject the proposed instruction diff.",
payload: {
version: 1,
prompt: "Apply this Reflection Coach instruction diff in a follow-up run?",
acceptLabel: "Accept",
rejectLabel: "Reject",
detailsMarkdown: [
"```diff",
" # Target Coder",
"",
" Work from the assigned issue.",
"+When finishing, name the exact verification command.",
"```",
].join("\n"),
target: {
type: "custom",
key: `agent:${target.id}:instructions`,
revisionId: "proposal-v1",
label: "Target Coder AGENTS.md diff",
},
},
}, {
agentId: coach.id,
});
const accepted = await interactionsSvc.acceptInteraction(
{ id: proposalIssueId, companyId, goalId: null, projectId: null },
acceptedProposal.id,
{},
{ userId: "board-user" },
);
expect(accepted.interaction).toMatchObject({
id: acceptedProposal.id,
kind: "request_confirmation",
status: "accepted",
});
expect(accepted.continuationIssue).toMatchObject({
id: proposalIssueId,
assigneeAgentId: coach.id,
assigneeUserId: null,
status: "todo",
});
expect(await readTargetInstructions()).toBe(originalInstructions);
await expect(applyAcceptedProposalFollowUp({
interactionId: acceptedProposal.id,
nextInstructions: acceptedInstructions,
})).resolves.toBe(true);
expect(await readTargetInstructions()).toBe(acceptedInstructions);
const rejectedProposal = await interactionsSvc.create({
id: proposalIssueId,
companyId,
}, {
kind: "request_confirmation",
continuationPolicy: "wake_assignee_on_accept",
idempotencyKey: "reflection-coach:proposal-v2",
title: "Review rejected coaching change",
summary: "Rejecting this diff must not mutate the target instructions.",
payload: {
version: 1,
prompt: "Apply this rejected Reflection Coach instruction diff?",
acceptLabel: "Accept",
rejectLabel: "Reject",
detailsMarkdown: [
"```diff",
"+This rejected line must not be applied.",
"```",
].join("\n"),
target: {
type: "custom",
key: `agent:${target.id}:instructions`,
revisionId: "proposal-v2",
label: "Target Coder AGENTS.md rejected diff",
},
},
}, {
agentId: coach.id,
});
const rejected = await interactionsSvc.rejectInteraction(
{ id: proposalIssueId, companyId },
rejectedProposal.id,
{ reason: "Not the right rule." },
{ userId: "board-user" },
);
expect(rejected).toMatchObject({
id: rejectedProposal.id,
kind: "request_confirmation",
status: "rejected",
result: expect.objectContaining({
outcome: "rejected",
reason: "Not the right rule.",
}),
});
await expect(applyAcceptedProposalFollowUp({
interactionId: rejectedProposal.id,
nextInstructions: `${acceptedInstructions}\nThis rejected line must not be applied.\n`,
})).resolves.toBe(false);
expect(await readTargetInstructions()).toBe(acceptedInstructions);
});
it("preserves Reflection Coach stock drift until explicit reset", async () => {
const companyId = await seedCompany();
const created = await builtInAgentService(db).ensure(companyId, "reflection-coach");
const agent = created.agent!;
const instructionsSvc = agentInstructionsService();
await writeInstructionEntry(agent, "AGENTS.md", "# Custom Reflection Coach\n\nDo not overwrite me.\n");
await db
.update(companySkills)
.set({ markdown: "---\nname: reflection-coach\n---\n\n# Custom skill\n" })
.where(eq(companySkills.companyId, companyId));
await db
.update(routines)
.set({ title: "DRIFTED BY TEST - do not clobber" })
.where(eq(routines.companyId, companyId));
const drifted = await builtInAgentService(db).ensure(companyId, "reflection-coach");
expect(drifted.resources.find((resource) => resource.resourceKind === "instructions")).toMatchObject({
stockStatus: "operator_modified",
resetAvailable: true,
});
expect(drifted.resources.find((resource) => resource.resourceKind === "skill")).toMatchObject({
stockStatus: "operator_modified",
resetAvailable: true,
});
expect(drifted.resources.find((resource) => resource.resourceKind === "routine")).toMatchObject({
stockStatus: "operator_modified",
resetAvailable: true,
});
expect((await instructionsSvc.readFile(drifted.agent!, "AGENTS.md")).content).toContain("Do not overwrite me.");
const [preservedRoutine] = await db.select().from(routines).where(eq(routines.companyId, companyId));
expect(preservedRoutine?.title).toBe("DRIFTED BY TEST - do not clobber");
const reset = await builtInAgentService(db).reset(companyId, "reflection-coach", {
resources: ["instructions", "routine"],
}, instructionOperator);
expect(reset.resources.find((resource) => resource.resourceKind === "instructions")).toMatchObject({
stockStatus: "stock_current",
resetAvailable: false,
});
expect(reset.resources.find((resource) => resource.resourceKind === "skill")).toMatchObject({
stockStatus: "operator_modified",
resetAvailable: true,
});
expect(reset.resources.find((resource) => resource.resourceKind === "routine")).toMatchObject({
stockStatus: "stock_current",
resetAvailable: false,
});
expect((await instructionsSvc.readFile(reset.agent!, "AGENTS.md")).content).toContain("You are Reflection Coach");
const [resetRoutine] = await db.select().from(routines).where(eq(routines.companyId, companyId));
expect(resetRoutine?.title).toBe("Review recent agent trajectories for coaching proposals");
});
});