Skip to content

The open-source app everyone uses to manage agents at work

Improve instructions bundle mode switching

dotta154a4a7ac18d
diff --git a/packages/shared/src/types/agent.ts b/packages/shared/src/types/agent.ts
index e33a1fb49b..61fe62fc00 100644
--- a/packages/shared/src/types/agent.ts
+++ b/packages/shared/src/types/agent.ts
@@ -31,6 +31,7 @@ export interface AgentInstructionsBundle {
companyId: string;
mode: AgentInstructionsBundleMode | null;
rootPath: string | null;
+ managedRootPath: string;
entryFile: string;
resolvedEntryPath: string | null;
editable: boolean;
diff --git a/server/src/__tests__/agent-instructions-routes.test.ts b/server/src/__tests__/agent-instructions-routes.test.ts
index 3924fc0480..4f6ca414f6 100644
--- a/server/src/__tests__/agent-instructions-routes.test.ts
+++ b/server/src/__tests__/agent-instructions-routes.test.ts
@@ -103,6 +103,7 @@ describe("agent instructions bundle routes", () => {
companyId: "company-1",
mode: "managed",
rootPath: "/tmp/agent-1",
+ managedRootPath: "/tmp/agent-1",
entryFile: "AGENTS.md",
resolvedEntryPath: "/tmp/agent-1/AGENTS.md",
editable: true,
@@ -161,6 +162,7 @@ describe("agent instructions bundle routes", () => {
expect(res.body).toMatchObject({
mode: "managed",
rootPath: "/tmp/agent-1",
+ managedRootPath: "/tmp/agent-1",
entryFile: "AGENTS.md",
});
expect(mockAgentInstructionsService.getBundle).toHaveBeenCalled();
diff --git a/server/src/__tests__/agent-instructions-service.test.ts b/server/src/__tests__/agent-instructions-service.test.ts
new file mode 100644
index 0000000000..8129b5ec11
--- /dev/null
+++ b/server/src/__tests__/agent-instructions-service.test.ts
@@ -0,0 +1,123 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { agentInstructionsService } from "../services/agent-instructions.js";
+
+type TestAgent = {
+ id: string;
+ companyId: string;
+ name: string;
+ adapterConfig: Record<string, unknown>;
+};
+
+async function makeTempDir(prefix: string) {
+ return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+function makeAgent(adapterConfig: Record<string, unknown>): TestAgent {
+ return {
+ id: "agent-1",
+ companyId: "company-1",
+ name: "Agent 1",
+ adapterConfig,
+ };
+}
+
+describe("agent instructions service", () => {
+ const originalPaperclipHome = process.env.PAPERCLIP_HOME;
+ const originalPaperclipInstanceId = process.env.PAPERCLIP_INSTANCE_ID;
+ const cleanupDirs = new Set<string>();
+
+ afterEach(async () => {
+ if (originalPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
+ else process.env.PAPERCLIP_HOME = originalPaperclipHome;
+ if (originalPaperclipInstanceId === undefined) delete process.env.PAPERCLIP_INSTANCE_ID;
+ else process.env.PAPERCLIP_INSTANCE_ID = originalPaperclipInstanceId;
+
+ await Promise.all([...cleanupDirs].map(async (dir) => {
+ await fs.rm(dir, { recursive: true, force: true });
+ cleanupDirs.delete(dir);
+ }));
+ });
+
+ it("copies the existing bundle into the managed root when switching to managed mode", async () => {
+ const paperclipHome = await makeTempDir("paperclip-agent-instructions-home-");
+ const externalRoot = await makeTempDir("paperclip-agent-instructions-external-");
+ cleanupDirs.add(paperclipHome);
+ cleanupDirs.add(externalRoot);
+ process.env.PAPERCLIP_HOME = paperclipHome;
+ process.env.PAPERCLIP_INSTANCE_ID = "test-instance";
+
+ await fs.writeFile(path.join(externalRoot, "AGENTS.md"), "# External Agent\n", "utf8");
+ await fs.mkdir(path.join(externalRoot, "docs"), { recursive: true });
+ await fs.writeFile(path.join(externalRoot, "docs", "TOOLS.md"), "## Tools\n", "utf8");
+
+ const svc = agentInstructionsService();
+ const agent = makeAgent({
+ instructionsBundleMode: "external",
+ instructionsRootPath: externalRoot,
+ instructionsEntryFile: "AGENTS.md",
+ instructionsFilePath: path.join(externalRoot, "AGENTS.md"),
+ });
+
+ const result = await svc.updateBundle(agent, { mode: "managed" });
+
+ expect(result.bundle.mode).toBe("managed");
+ expect(result.bundle.managedRootPath).toBe(
+ path.join(
+ paperclipHome,
+ "instances",
+ "test-instance",
+ "companies",
+ "company-1",
+ "agents",
+ "agent-1",
+ "instructions",
+ ),
+ );
+ expect(result.bundle.files.map((file) => file.path)).toEqual(["AGENTS.md", "docs/TOOLS.md"]);
+ await expect(fs.readFile(path.join(result.bundle.managedRootPath, "AGENTS.md"), "utf8")).resolves.toBe("# External Agent\n");
+ await expect(fs.readFile(path.join(result.bundle.managedRootPath, "docs", "TOOLS.md"), "utf8")).resolves.toBe("## Tools\n");
+ });
+
+ it("creates the target entry file when switching to a new external root", async () => {
+ const paperclipHome = await makeTempDir("paperclip-agent-instructions-home-");
+ const managedRoot = path.join(
+ paperclipHome,
+ "instances",
+ "test-instance",
+ "companies",
+ "company-1",
+ "agents",
+ "agent-1",
+ "instructions",
+ );
+ const externalRoot = await makeTempDir("paperclip-agent-instructions-new-external-");
+ cleanupDirs.add(paperclipHome);
+ cleanupDirs.add(externalRoot);
+ process.env.PAPERCLIP_HOME = paperclipHome;
+ process.env.PAPERCLIP_INSTANCE_ID = "test-instance";
+
+ await fs.mkdir(managedRoot, { recursive: true });
+ await fs.writeFile(path.join(managedRoot, "AGENTS.md"), "# Managed Agent\n", "utf8");
+
+ const svc = agentInstructionsService();
+ const agent = makeAgent({
+ instructionsBundleMode: "managed",
+ instructionsRootPath: managedRoot,
+ instructionsEntryFile: "AGENTS.md",
+ instructionsFilePath: path.join(managedRoot, "AGENTS.md"),
+ });
+
+ const result = await svc.updateBundle(agent, {
+ mode: "external",
+ rootPath: externalRoot,
+ entryFile: "docs/AGENTS.md",
+ });
+
+ expect(result.bundle.mode).toBe("external");
+ expect(result.bundle.rootPath).toBe(externalRoot);
+ await expect(fs.readFile(path.join(externalRoot, "docs", "AGENTS.md"), "utf8")).resolves.toBe("# Managed Agent\n");
+ });
+});
diff --git a/server/src/services/agent-instructions.ts b/server/src/services/agent-instructions.ts
index 197fe96076..086d5fbb91 100644
--- a/server/src/services/agent-instructions.ts
+++ b/server/src/services/agent-instructions.ts
@@ -42,6 +42,7 @@ type AgentInstructionsBundle = {
companyId: string;
mode: BundleMode | null;
rootPath: string | null;
+ managedRootPath: string;
entryFile: string;
resolvedEntryPath: string | null;
editable: boolean;
@@ -266,6 +267,7 @@ function toBundle(agent: AgentLike, state: BundleState, files: AgentInstructions
companyId: agent.companyId,
mode: state.mode,
rootPath: state.rootPath,
+ managedRootPath: resolveManagedInstructionsRoot(agent),
entryFile: state.entryFile,
resolvedEntryPath: state.resolvedEntryPath,
editable: Boolean(state.rootPath),
@@ -299,6 +301,21 @@ function applyBundleConfig(
return next;
}
+async function writeBundleFiles(
+ rootPath: string,
+ files: Record<string, string>,
+ options?: { overwriteExisting?: boolean },
+) {
+ for (const [relativePath, content] of Object.entries(files)) {
+ const normalizedPath = normalizeRelativeFilePath(relativePath);
+ const absolutePath = resolvePathWithinRoot(rootPath, normalizedPath);
+ const existingStat = await statIfExists(absolutePath);
+ if (existingStat?.isFile() && !options?.overwriteExisting) continue;
+ await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+ await fs.writeFile(absolutePath, content, "utf8");
+ }
+}
+
export function syncInstructionsBundleConfigFromFilePath(
agent: AgentLike,
adapterConfig: Record<string, unknown>,
@@ -440,6 +457,17 @@ export function agentInstructionsService() {
await fs.mkdir(nextRootPath, { recursive: true });
+ const existingFiles = await listFilesRecursive(nextRootPath);
+ const exported = await exportFiles(agent);
+ if (existingFiles.length === 0) {
+ await writeBundleFiles(nextRootPath, exported.files);
+ }
+ const refreshedFiles = existingFiles.length === 0 ? await listFilesRecursive(nextRootPath) : existingFiles;
+ if (!refreshedFiles.includes(nextEntryFile)) {
+ const nextEntryContent = exported.files[nextEntryFile] ?? exported.files[exported.entryFile] ?? "";
+ await writeBundleFiles(nextRootPath, { [nextEntryFile]: nextEntryContent });
+ }
+
const nextConfig = applyBundleConfig(state.config, {
mode: nextMode,
rootPath: nextRootPath,
diff --git a/ui/src/pages/AgentDetail.tsx b/ui/src/pages/AgentDetail.tsx
index 22823e99f8..736ab87622 100644
--- a/ui/src/pages/AgentDetail.tsx
+++ b/ui/src/pages/AgentDetail.tsx
@@ -1513,6 +1513,11 @@ function PromptsTab({
const containerRef = useRef<HTMLDivElement>(null);
const [awaitingRefresh, setAwaitingRefresh] = useState(false);
const lastFileVersionRef = useRef<string | null>(null);
+ const externalBundleRef = useRef<{
+ rootPath: string;
+ entryFile: string;
+ selectedFile: string;
+ } | null>(null);
const isLocal =
agent.adapterType === "claude_local" ||
@@ -1528,23 +1533,35 @@ function PromptsTab({
enabled: Boolean(companyId && isLocal),
});
- const currentMode = bundleDraft?.mode ?? bundle?.mode ?? "managed";
+ const persistedMode = bundle?.mode ?? "managed";
+ const persistedRootPath = persistedMode === "managed"
+ ? (bundle?.managedRootPath ?? bundle?.rootPath ?? "")
+ : (bundle?.rootPath ?? "");
+ const currentMode = bundleDraft?.mode ?? persistedMode;
const currentEntryFile = bundleDraft?.entryFile ?? bundle?.entryFile ?? "AGENTS.md";
- const currentRootPath = bundleDraft?.rootPath ?? bundle?.rootPath ?? "";
+ const currentRootPath = bundleDraft?.rootPath ?? persistedRootPath;
const fileOptions = useMemo(
() => bundle?.files.map((file) => file.path) ?? [],
[bundle],
);
+ const bundleMatchesDraft = Boolean(
+ bundle &&
+ currentMode === persistedMode &&
+ currentEntryFile === bundle.entryFile &&
+ currentRootPath === persistedRootPath,
+ );
const visibleFilePaths = useMemo(
- () => [...new Set([currentEntryFile, ...fileOptions])],
- [currentEntryFile, fileOptions],
+ () => bundleMatchesDraft
+ ? [...new Set([currentEntryFile, ...fileOptions])]
+ : [currentEntryFile],
+ [bundleMatchesDraft, currentEntryFile, fileOptions],
);
const fileTree = useMemo(
() => buildFileTree(Object.fromEntries(visibleFilePaths.map((filePath) => [filePath, ""]))),
[visibleFilePaths],
);
const selectedOrEntryFile = selectedFile || currentEntryFile;
- const selectedFileExists = fileOptions.includes(selectedOrEntryFile);
+ const selectedFileExists = bundleMatchesDraft && fileOptions.includes(selectedOrEntryFile);
const selectedFileSummary = bundle?.files.find((file) => file.path === selectedOrEntryFile) ?? null;
const { data: selectedFileDetail, isLoading: fileLoading } = useQuery({
@@ -1603,6 +1620,10 @@ function PromptsTab({
useEffect(() => {
if (!bundle) return;
+ if (!bundleMatchesDraft) {
+ if (selectedFile !== currentEntryFile) setSelectedFile(currentEntryFile);
+ return;
+ }
const availablePaths = bundle.files.map((file) => file.path);
if (availablePaths.length === 0) {
if (selectedFile !== bundle.entryFile) setSelectedFile(bundle.entryFile);
@@ -1611,7 +1632,7 @@ function PromptsTab({
if (!availablePaths.includes(selectedFile)) {
setSelectedFile(availablePaths.includes(bundle.entryFile) ? bundle.entryFile : availablePaths[0]!);
}
- }, [bundle, selectedFile]);
+ }, [bundle, bundleMatchesDraft, currentEntryFile, selectedFile]);
useEffect(() => {
const nextExpanded = new Set<string>();
@@ -1627,7 +1648,9 @@ function PromptsTab({
}, [visibleFilePaths]);
useEffect(() => {
- const versionKey = selectedFileDetail ? `${selectedFileDetail.path}:${selectedFileDetail.content}` : `draft:${selectedOrEntryFile}`;
+ const versionKey = selectedFileExists && selectedFileDetail
+ ? `${selectedFileDetail.path}:${selectedFileDetail.content}`
+ : `draft:${currentMode}:${currentRootPath}:${selectedOrEntryFile}`;
if (awaitingRefresh) {
setAwaitingRefresh(false);
setBundleDraft(null);
@@ -1639,27 +1662,36 @@ function PromptsTab({
setDraft(null);
lastFileVersionRef.current = versionKey;
}
- }, [awaitingRefresh, selectedFileDetail, selectedOrEntryFile]);
+ }, [awaitingRefresh, currentMode, currentRootPath, selectedFileDetail, selectedFileExists, selectedOrEntryFile]);
useEffect(() => {
if (!bundle) return;
setBundleDraft((current) => {
if (current) return current;
return {
- mode: bundle.mode ?? "managed",
- rootPath: bundle.rootPath ?? "",
+ mode: persistedMode,
+ rootPath: persistedRootPath,
entryFile: bundle.entryFile,
};
});
- }, [bundle]);
+ }, [bundle, persistedMode, persistedRootPath]);
+
+ useEffect(() => {
+ if (!bundle || currentMode !== "external") return;
+ externalBundleRef.current = {
+ rootPath: currentRootPath,
+ entryFile: currentEntryFile,
+ selectedFile: selectedOrEntryFile,
+ };
+ }, [bundle, currentEntryFile, currentMode, currentRootPath, selectedOrEntryFile]);
const currentContent = selectedFileExists ? (selectedFileDetail?.content ?? "") : "";
const displayValue = draft ?? currentContent;
const bundleDirty = Boolean(
bundleDraft &&
(
- bundleDraft.mode !== (bundle?.mode ?? "managed") ||
- bundleDraft.rootPath !== (bundle?.rootPath ?? "") ||
+ bundleDraft.mode !== persistedMode ||
+ bundleDraft.rootPath !== persistedRootPath ||
bundleDraft.entryFile !== (bundle?.entryFile ?? "AGENTS.md")
),
);
@@ -1710,13 +1742,13 @@ function PromptsTab({
setDraft(null);
if (bundle) {
setBundleDraft({
- mode: bundle.mode ?? "managed",
- rootPath: bundle.rootPath ?? "",
+ mode: persistedMode,
+ rootPath: persistedRootPath,
entryFile: bundle.entryFile,
});
}
} : null);
- }, [bundle, isDirty, onCancelActionChange]);
+ }, [bundle, isDirty, onCancelActionChange, persistedMode, persistedRootPath]);
const handleSeparatorDrag = useCallback((event: React.MouseEvent) => {
event.preventDefault();
@@ -1754,7 +1786,7 @@ function PromptsTab({
}
return (
- <div className="max-w-6xl space-y-4">
+ <div className="max-w-6xl space-y-6">
{(bundle?.warnings ?? []).length > 0 && (
<div className="space-y-2">
{(bundle?.warnings ?? []).map((warning) => (
@@ -1907,7 +1939,7 @@ function PromptsTab({
<ChevronRight className="h-3 w-3 transition-transform group-data-[state=open]:rotate-90" />
Advanced
</CollapsibleTrigger>
- <CollapsibleContent className="pt-3 space-y-3">
+ <CollapsibleContent className="pt-4 pb-4 space-y-4">
<TooltipProvider>
<label className="space-y-1">
<span className="text-xs font-medium text-muted-foreground flex items-center gap-1">
@@ -1926,11 +1958,22 @@ function PromptsTab({
type="button"
size="sm"
variant={currentMode === "managed" ? "default" : "outline"}
- onClick={() => setBundleDraft((current) => ({
- mode: "managed",
- rootPath: current?.rootPath ?? bundle?.rootPath ?? "",
- entryFile: current?.entryFile ?? bundle?.entryFile ?? "AGENTS.md",
- }))}
+ onClick={() => {
+ if (currentMode === "external") {
+ externalBundleRef.current = {
+ rootPath: currentRootPath,
+ entryFile: currentEntryFile,
+ selectedFile: selectedOrEntryFile,
+ };
+ }
+ const nextEntryFile = currentEntryFile || "AGENTS.md";
+ setBundleDraft({
+ mode: "managed",
+ rootPath: bundle?.managedRootPath ?? currentRootPath,
+ entryFile: nextEntryFile,
+ });
+ setSelectedFile(nextEntryFile);
+ }}
>
Managed
</Button>
@@ -1938,17 +1981,22 @@ function PromptsTab({
type="button"
size="sm"
variant={currentMode === "external" ? "default" : "outline"}
- onClick={() => setBundleDraft((current) => ({
- mode: "external",
- rootPath: current?.rootPath ?? bundle?.rootPath ?? "",
- entryFile: current?.entryFile ?? bundle?.entryFile ?? "AGENTS.md",
- }))}
+ onClick={() => {
+ const externalBundle = externalBundleRef.current;
+ const nextEntryFile = externalBundle?.entryFile ?? currentEntryFile ?? "AGENTS.md";
+ setBundleDraft({
+ mode: "external",
+ rootPath: externalBundle?.rootPath ?? (bundle?.mode === "external" ? (bundle.rootPath ?? "") : ""),
+ entryFile: nextEntryFile,
+ });
+ setSelectedFile(externalBundle?.selectedFile ?? nextEntryFile);
+ }}
>
External
</Button>
</div>
</label>
- <div className="grid gap-3 sm:grid-cols-3">
+ <div className="grid gap-4 sm:grid-cols-2">
<label className="space-y-1">
<span className="text-xs font-medium text-muted-foreground flex items-center gap-1">
Root path
@@ -1963,7 +2011,7 @@ function PromptsTab({
</span>
{currentMode === "managed" ? (
<div className="flex items-center gap-1.5 font-mono text-sm text-muted-foreground">
- <span className="truncate">{currentRootPath || "(managed)"}</span>
+ <span className="min-w-0 break-all">{currentRootPath || "(managed)"}</span>
{currentRootPath && (
<CopyText text={currentRootPath} className="shrink-0">
<Copy className="h-3.5 w-3.5" />
@@ -1974,11 +2022,19 @@ function PromptsTab({
<div className="flex items-center gap-1.5">
<Input
value={currentRootPath}
- onChange={(event) => setBundleDraft((current) => ({
- mode: current?.mode ?? bundle?.mode ?? "managed",
- rootPath: event.target.value,
- entryFile: current?.entryFile ?? bundle?.entryFile ?? "AGENTS.md",
- }))}
+ onChange={(event) => {
+ const nextRootPath = event.target.value;
+ externalBundleRef.current = {
+ rootPath: nextRootPath,
+ entryFile: currentEntryFile,
+ selectedFile: selectedOrEntryFile,
+ };
+ setBundleDraft({
+ mode: "external",
+ rootPath: nextRootPath,
+ entryFile: currentEntryFile,
+ });
+ }}
className="font-mono text-sm"
placeholder="/absolute/path/to/agent/prompts"
/>
@@ -2006,14 +2062,22 @@ function PromptsTab({
value={currentEntryFile}
onChange={(event) => {
const nextEntryFile = event.target.value || "AGENTS.md";
- if (selectedOrEntryFile === currentEntryFile) {
- setSelectedFile(nextEntryFile);
+ const nextSelectedFile = selectedOrEntryFile === currentEntryFile
+ ? nextEntryFile
+ : selectedOrEntryFile;
+ if (currentMode === "external") {
+ externalBundleRef.current = {
+ rootPath: currentRootPath,
+ entryFile: nextEntryFile,
+ selectedFile: nextSelectedFile,
+ };
}
- setBundleDraft((current) => ({
- mode: current?.mode ?? bundle?.mode ?? "managed",
- rootPath: current?.rootPath ?? bundle?.rootPath ?? "",
+ if (selectedOrEntryFile === currentEntryFile) setSelectedFile(nextEntryFile);
+ setBundleDraft({
+ mode: currentMode,
+ rootPath: currentRootPath,
entryFile: nextEntryFile,
- }));
+ });
}}
className="font-mono text-sm"
/>