Add agent instructions bundle editing

Expose first-class instructions bundle APIs, preserve agent prompt bundles in portability flows, and replace the Agent Detail prompts tab with file-backed bundle editing while retiring bootstrap prompt UI.

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

server/src/__tests__/agent-instructions-routes.test.ts

@@ -0,0 +1,185 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { agentRoutes } from "../routes/agents.js";
+import { errorHandler } from "../middleware/index.js";
+
+const mockAgentService = vi.hoisted(() => ({
+  getById: vi.fn(),
+  update: vi.fn(),
+  resolveByReference: vi.fn(),
+}));
+
+const mockAgentInstructionsService = vi.hoisted(() => ({
+  getBundle: vi.fn(),
+  readFile: vi.fn(),
+  updateBundle: vi.fn(),
+  writeFile: vi.fn(),
+  deleteFile: vi.fn(),
+  exportFiles: vi.fn(),
+  ensureManagedBundle: vi.fn(),
+  materializeManagedBundle: vi.fn(),
+}));
+
+const mockAccessService = vi.hoisted(() => ({
+  canUser: vi.fn(),
+  hasPermission: vi.fn(),
+}));
+
+const mockSecretService = vi.hoisted(() => ({
+  resolveAdapterConfigForRuntime: vi.fn(),
+  normalizeAdapterConfigForPersistence: vi.fn(async (_companyId: string, config: Record<string, unknown>) => config),
+}));
+
+const mockLogActivity = vi.hoisted(() => vi.fn());
+
+vi.mock("../services/index.js", () => ({
+  agentService: () => mockAgentService,
+  agentInstructionsService: () => mockAgentInstructionsService,
+  accessService: () => mockAccessService,
+  approvalService: () => ({}),
+  companySkillService: () => ({ listRuntimeSkillEntries: vi.fn() }),
+  budgetService: () => ({}),
+  heartbeatService: () => ({}),
+  issueApprovalService: () => ({}),
+  issueService: () => ({}),
+  logActivity: mockLogActivity,
+  secretService: () => mockSecretService,
+  syncInstructionsBundleConfigFromFilePath: vi.fn((_agent, config) => config),
+  workspaceOperationService: () => ({}),
+}));
+
+vi.mock("../adapters/index.js", () => ({
+  findServerAdapter: vi.fn(),
+  listAdapterModels: vi.fn(),
+}));
+
+function createApp() {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = {
+      type: "board",
+      userId: "local-board",
+      companyIds: ["company-1"],
+      source: "local_implicit",
+      isInstanceAdmin: false,
+    };
+    next();
+  });
+  app.use("/api", agentRoutes({} as any));
+  app.use(errorHandler);
+  return app;
+}
+
+function makeAgent() {
+  return {
+    id: "11111111-1111-4111-8111-111111111111",
+    companyId: "company-1",
+    name: "Agent",
+    role: "engineer",
+    title: "Engineer",
+    status: "active",
+    reportsTo: null,
+    capabilities: null,
+    adapterType: "codex_local",
+    adapterConfig: {},
+    runtimeConfig: {},
+    permissions: null,
+    updatedAt: new Date(),
+  };
+}
+
+describe("agent instructions bundle routes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockAgentService.getById.mockResolvedValue(makeAgent());
+    mockAgentService.update.mockImplementation(async (_id: string, patch: Record<string, unknown>) => ({
+      ...makeAgent(),
+      adapterConfig: patch.adapterConfig ?? {},
+    }));
+    mockAgentInstructionsService.getBundle.mockResolvedValue({
+      agentId: "11111111-1111-4111-8111-111111111111",
+      companyId: "company-1",
+      mode: "managed",
+      rootPath: "/tmp/agent-1",
+      entryFile: "AGENTS.md",
+      resolvedEntryPath: "/tmp/agent-1/AGENTS.md",
+      editable: true,
+      warnings: [],
+      legacyPromptTemplateActive: false,
+      legacyBootstrapPromptTemplateActive: false,
+      files: [{ path: "AGENTS.md", size: 12, language: "markdown", markdown: true, isEntryFile: true }],
+    });
+    mockAgentInstructionsService.readFile.mockResolvedValue({
+      path: "AGENTS.md",
+      size: 12,
+      language: "markdown",
+      markdown: true,
+      isEntryFile: true,
+      editable: true,
+      content: "# Agent\n",
+    });
+    mockAgentInstructionsService.writeFile.mockResolvedValue({
+      bundle: null,
+      file: {
+        path: "AGENTS.md",
+        size: 18,
+        language: "markdown",
+        markdown: true,
+        isEntryFile: true,
+        editable: true,
+        content: "# Updated Agent\n",
+      },
+      adapterConfig: {
+        instructionsBundleMode: "managed",
+        instructionsRootPath: "/tmp/agent-1",
+        instructionsEntryFile: "AGENTS.md",
+        instructionsFilePath: "/tmp/agent-1/AGENTS.md",
+      },
+    });
+  });
+
+  it("returns bundle metadata", async () => {
+    const res = await request(createApp())
+      .get("/api/agents/11111111-1111-4111-8111-111111111111/instructions-bundle?companyId=company-1");
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(res.body).toMatchObject({
+      mode: "managed",
+      rootPath: "/tmp/agent-1",
+      entryFile: "AGENTS.md",
+    });
+    expect(mockAgentInstructionsService.getBundle).toHaveBeenCalled();
+  });
+
+  it("writes a bundle file and persists compatibility config", async () => {
+    const res = await request(createApp())
+      .put("/api/agents/11111111-1111-4111-8111-111111111111/instructions-bundle/file?companyId=company-1")
+      .send({
+        path: "AGENTS.md",
+        content: "# Updated Agent\n",
+        clearLegacyPromptTemplate: true,
+      });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockAgentInstructionsService.writeFile).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "11111111-1111-4111-8111-111111111111" }),
+      "AGENTS.md",
+      "# Updated Agent\n",
+      { clearLegacyPromptTemplate: true },
+    );
+    expect(mockAgentService.update).toHaveBeenCalledWith(
+      "11111111-1111-4111-8111-111111111111",
+      expect.objectContaining({
+        adapterConfig: expect.objectContaining({
+          instructionsBundleMode: "managed",
+          instructionsRootPath: "/tmp/agent-1",
+          instructionsEntryFile: "AGENTS.md",
+          instructionsFilePath: "/tmp/agent-1/AGENTS.md",
+        }),
+      }),
+      expect.any(Object),
+    );
+  });
+});

server/src/__tests__/agent-skills-routes.test.ts

@@ -20,6 +20,16 @@ const mockBudgetService = vi.hoisted(() => ({}));
 const mockHeartbeatService = vi.hoisted(() => ({}));
 const mockIssueApprovalService = vi.hoisted(() => ({}));
 const mockWorkspaceOperationService = vi.hoisted(() => ({}));
+const mockAgentInstructionsService = vi.hoisted(() => ({
+  getBundle: vi.fn(),
+  readFile: vi.fn(),
+  updateBundle: vi.fn(),
+  writeFile: vi.fn(),
+  deleteFile: vi.fn(),
+  exportFiles: vi.fn(),
+  ensureManagedBundle: vi.fn(),
+  materializeManagedBundle: vi.fn(),
+}));
 
 const mockCompanySkillService = vi.hoisted(() => ({
   listRuntimeSkillEntries: vi.fn(),
@@ -27,6 +37,7 @@ const mockCompanySkillService = vi.hoisted(() => ({
 
 const mockSecretService = vi.hoisted(() => ({
   resolveAdapterConfigForRuntime: vi.fn(),
+  normalizeAdapterConfigForPersistence: vi.fn(async (_companyId: string, config: Record<string, unknown>) => config),
 }));
 
 const mockLogActivity = vi.hoisted(() => vi.fn());
@@ -38,6 +49,7 @@ const mockAdapter = vi.hoisted(() => ({
 
 vi.mock("../services/index.js", () => ({
   agentService: () => mockAgentService,
+  agentInstructionsService: () => mockAgentInstructionsService,
   accessService: () => mockAccessService,
   approvalService: () => mockApprovalService,
   companySkillService: () => mockCompanySkillService,
@@ -47,6 +59,7 @@ vi.mock("../services/index.js", () => ({
   issueService: () => ({}),
   logActivity: mockLogActivity,
   secretService: () => mockSecretService,
+  syncInstructionsBundleConfigFromFilePath: vi.fn((_agent, config) => config),
   workspaceOperationService: () => mockWorkspaceOperationService,
 }));
 

server/src/__tests__/company-portability.test.ts

@@ -36,6 +36,11 @@ const companySkillSvc = {
   importPackageFiles: vi.fn(),
 };
 
+const agentInstructionsSvc = {
+  exportFiles: vi.fn(),
+  materializeManagedBundle: vi.fn(),
+};
+
 vi.mock("../services/companies.js", () => ({
   companyService: () => companySvc,
 }));
@@ -60,6 +65,10 @@ vi.mock("../services/company-skills.js", () => ({
   companySkillService: () => companySkillSvc,
 }));
 
+vi.mock("../services/agent-instructions.js", () => ({
+  agentInstructionsService: () => agentInstructionsSvc,
+}));
+
 const { companyPortabilityService } = await import("../services/company-portability.js");
 
 describe("company portability", () => {
@@ -231,6 +240,21 @@ describe("company portability", () => {
       };
     });
     companySkillSvc.importPackageFiles.mockResolvedValue([]);
+    agentInstructionsSvc.exportFiles.mockImplementation(async (agent: { name: string }) => ({
+      files: { "AGENTS.md": agent.name === "CMO" ? "You are CMO." : "You are ClaudeCoder." },
+      entryFile: "AGENTS.md",
+      warnings: [],
+    }));
+    agentInstructionsSvc.materializeManagedBundle.mockImplementation(async (agent: { adapterConfig: Record<string, unknown> }) => ({
+      bundle: null,
+      adapterConfig: {
+        ...agent.adapterConfig,
+        instructionsBundleMode: "managed",
+        instructionsRootPath: `/tmp/${agent.id}`,
+        instructionsEntryFile: "AGENTS.md",
+        instructionsFilePath: `/tmp/${agent.id}/AGENTS.md`,
+      },
+    }));
   });
 
   it("exports referenced skills as stubs by default with sanitized Paperclip extension data", async () => {
@@ -536,14 +560,24 @@ describe("company portability", () => {
     expect(agentSvc.create).toHaveBeenCalledWith("company-imported", expect.objectContaining({
       adapterType: "codex_local",
       adapterConfig: expect.objectContaining({
-        promptTemplate: "You are ClaudeCoder.",
         dangerouslyBypassApprovalsAndSandbox: true,
       }),
     }));
     expect(agentSvc.create).toHaveBeenCalledWith("company-imported", expect.objectContaining({
       adapterConfig: expect.not.objectContaining({
         instructionsFilePath: expect.anything(),
+        promptTemplate: expect.anything(),
       }),
     }));
+    expect(agentInstructionsSvc.materializeManagedBundle).toHaveBeenCalledWith(
+      expect.objectContaining({ name: "ClaudeCoder" }),
+      expect.objectContaining({
+        "AGENTS.md": expect.stringContaining("You are ClaudeCoder."),
+      }),
+      expect.objectContaining({
+        clearLegacyPromptTemplate: true,
+        replaceExisting: true,
+      }),
+    );
   });
 });