The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(ui): use prose editor for markdown agent instructions (#9332)
Dotta9a1d4b7983df
diff --git a/ui/src/index.css b/ui/src/index.cssindex 14e234e4e3..c76beed8ae 100644--- a/ui/src/index.css+++ b/ui/src/index.css@@ -1470,7 +1470,7 @@ span.paperclip-mention-chip[data-mention-kind="external-object"] {--hex-eab308: #eab308; /* ActivityCharts.tsx — priority 'medium'; also the 0.5-0.8 success-rate bar tint. */--hex-6b7280: #6b7280; /* ActivityCharts.tsx — priority 'low' + unknown-status statusColors fallback. */--hex-10b981: #10b981; /* ActivityCharts.tsx — >=0.8 success-rate bar tint; also the run-activity 'succeeded' segment. */- --hex-737373: #737373; /* ActivityCharts.tsx — run activity "other" segment tint. */+ --hex-737373: #737373; /* ActivityCharts.tsx — run activity 'other' segment tint. */--project-none: #64748b; /* Semantic rename of --hex-64748b (DECISION-SHEET.md A3, value unchanged). 'No project assigned' muted-slate fallback (TOKEN-AUDIT.md 1.3) across Routines/MarkdownEditor/RoutineRunVariablesDialog/RoutineList/IssueColumns/editable-sections; also ActivityCharts.tsx status 'backlog'. */--project-seed: #6366f1; /* Semantic rename of --hex-6366f1 (DECISION-SHEET.md A3, value unchanged). Project-color-fallback indigo seed default (ProjectDetail/PipelineSettings/IssueProperties/NewIssueDialog) — new-project-color-picker-seed family per TOKEN-AUDIT.md 1.3. */--liveness-blue: #2563eb; /* DECISION-SHEET.md A6: IssueChatThread.tsx human-message 'liveness blue' bubble (PAP-95 rev 5). Same value as --status-task-in_progress by coincidence, decoupled on purpose so a future status-hue change doesn't drag the chat bubble along. */diff --git a/ui/src/pages/AgentDetail.instructions.test.tsx b/ui/src/pages/AgentDetail.instructions.test.tsxnew file mode 100644index 0000000000..a255227770--- /dev/null+++ b/ui/src/pages/AgentDetail.instructions.test.tsx@@ -0,0 +1,389 @@+// @vitest-environment jsdom++import type { ComponentProps } from "react";+import { flushSync } from "react-dom";+import { createRoot, type Root } from "react-dom/client";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import type { Agent, AgentInstructionsBundle, AgentInstructionsFileDetail, AgentInstructionsFileSummary } from "@paperclipai/shared";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { PromptsTab } from "./AgentDetail";++const mockAgentsApi = vi.hoisted(() => ({+ instructionsBundle: vi.fn(),+ instructionsFile: vi.fn(),+ updateInstructionsBundle: vi.fn(),+ saveInstructionsFile: vi.fn(),+ deleteInstructionsFile: vi.fn(),+}));++const markdownEditorRenderMock = vi.hoisted(() => vi.fn());++vi.mock("../api/agents", () => ({+ agentsApi: mockAgentsApi,+}));++vi.mock("../api/assets", () => ({+ assetsApi: {+ uploadImage: vi.fn(async () => ({ contentPath: "/assets/uploaded-image.png" })),+ },+}));++vi.mock("../context/CompanyContext", () => ({+ useCompany: () => ({ selectedCompanyId: "company-1" }),+}));++vi.mock("../context/SidebarContext", () => ({+ useSidebar: () => ({ isMobile: false }),+}));++vi.mock("@/adapters/use-adapter-capabilities", () => ({+ useAdapterCapabilities: () => () => ({+ supportsInstructionsBundle: true,+ supportsSkills: true,+ supportsLocalAgentJwt: true,+ requiresMaterializedRuntimeSkills: false,+ supportsModelProfiles: true,+ }),+}));++vi.mock("../components/MarkdownEditor", () => ({+ MarkdownEditor: ({+ value,+ onChange,+ placeholder,+ contentClassName,+ imageUploadHandler,+ }: {+ value: string;+ onChange: (value: string) => void;+ placeholder?: string;+ contentClassName?: string;+ imageUploadHandler?: (file: File) => Promise<string>;+ }) => {+ markdownEditorRenderMock({+ value,+ contentClassName,+ hasImageUploadHandler: Boolean(imageUploadHandler),+ });+ return (+ <textarea+ data-testid="markdown-editor"+ aria-label="Markdown editor"+ className={contentClassName}+ placeholder={placeholder}+ value={value}+ onChange={(event) => onChange(event.target.value)}+ />+ );+ },+}));++// eslint-disable-next-line @typescript-eslint/no-explicit-any+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;++async function act(callback: () => void | Promise<void>) {+ let result: void | Promise<void> = undefined;+ flushSync(() => {+ result = callback();+ });+ await result;+}++async function flushReact() {+ await act(async () => {+ await Promise.resolve();+ await new Promise((resolve) => window.setTimeout(resolve, 0));+ });+}++async function waitFor<T>(assertion: () => T): Promise<T> {+ let lastError: unknown;+ for (let i = 0; i < 20; i++) {+ try {+ return assertion();+ } catch (error) {+ lastError = error;+ await flushReact();+ }+ }+ throw lastError;+}++function setNativeValue(element: HTMLInputElement | HTMLTextAreaElement, value: string) {+ const prototype = element instanceof HTMLTextAreaElement+ ? HTMLTextAreaElement.prototype+ : HTMLInputElement.prototype;+ const setter = Object.getOwnPropertyDescriptor(prototype, "value")?.set;+ setter?.call(element, value);+ element.dispatchEvent(new Event("input", { bubbles: true }));+}++function buttonByText(container: HTMLElement, text: string) {+ const button = Array.from(container.querySelectorAll("button"))+ .find((candidate) => candidate.textContent?.trim() === text);+ if (!button) throw new Error(`Button not found: ${text}`);+ return button as HTMLButtonElement;+}++function makeAgent(overrides: Partial<Agent> = {}): Agent {+ return {+ id: "agent-1",+ companyId: "company-1",+ name: "Codex Coder",+ urlKey: "codexcoder",+ role: "engineer",+ title: null,+ icon: null,+ status: "active",+ reportsTo: null,+ capabilities: null,+ adapterType: "codex_local",+ adapterConfig: {},+ runtimeConfig: {},+ budgetMonthlyCents: 0,+ spentMonthlyCents: 0,+ pauseReason: null,+ pausedAt: null,+ permissions: { canCreateAgents: false },+ lastHeartbeatAt: null,+ metadata: null,+ createdAt: new Date("2026-01-01T00:00:00Z"),+ updatedAt: new Date("2026-01-01T00:00:00Z"),+ ...overrides,+ };+}++function makeSummary(+ path: string,+ entryFile: string,+ overrides: Partial<AgentInstructionsFileSummary> = {},+): AgentInstructionsFileSummary {+ const markdown = path.toLowerCase().endsWith(".md");+ return {+ path,+ size: 24,+ language: markdown ? "markdown" : "text",+ markdown,+ isEntryFile: path === entryFile,+ editable: true,+ deprecated: false,+ virtual: false,+ ...overrides,+ };+}++function makeDetail(+ summary: AgentInstructionsFileSummary,+ content = "# Agent instructions",+ overrides: Partial<AgentInstructionsFileDetail> = {},+): AgentInstructionsFileDetail {+ return {+ ...summary,+ content,+ ...overrides,+ };+}++function makeBundle(+ entryFile: string,+ files: AgentInstructionsFileSummary[],+ overrides: Partial<AgentInstructionsBundle> = {},+): AgentInstructionsBundle {+ return {+ agentId: "agent-1",+ companyId: "company-1",+ mode: "managed",+ rootPath: "/paperclip/agents/agent-1/instructions",+ managedRootPath: "/paperclip/agents/agent-1/instructions",+ entryFile,+ resolvedEntryPath: `/paperclip/agents/agent-1/instructions/${entryFile}`,+ editable: true,+ warnings: [],+ legacyPromptTemplateActive: false,+ legacyBootstrapPromptTemplateActive: false,+ files,+ ...overrides,+ };+}++describe("PromptsTab instruction editor", () => {+ let container: HTMLDivElement;+ let root: Root | null;+ let queryClient: QueryClient;+ let saveAction: (() => void) | null;++ beforeEach(() => {+ container = document.createElement("div");+ document.body.appendChild(container);+ root = null;+ queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false }, mutations: { retry: false } },+ });+ saveAction = null;+ markdownEditorRenderMock.mockClear();+ Object.values(mockAgentsApi).forEach((mock) => mock.mockReset());+ mockAgentsApi.updateInstructionsBundle.mockResolvedValue({});+ mockAgentsApi.saveInstructionsFile.mockImplementation(async (_agentId, data) => ({+ path: data.path,+ size: data.content.length,+ language: "markdown",+ markdown: true,+ isEntryFile: true,+ editable: true,+ deprecated: false,+ virtual: false,+ content: data.content,+ }));+ mockAgentsApi.deleteInstructionsFile.mockResolvedValue({});+ });++ afterEach(async () => {+ if (root) {+ await act(async () => {+ root?.unmount();+ });+ }+ queryClient.clear();+ container.remove();+ document.body.innerHTML = "";+ vi.clearAllMocks();+ });++ async function renderPromptsTab(+ bundle: AgentInstructionsBundle,+ details: Record<string, AgentInstructionsFileDetail>,+ props: Partial<ComponentProps<typeof PromptsTab>> = {},+ ) {+ mockAgentsApi.instructionsBundle.mockResolvedValue(bundle);+ mockAgentsApi.instructionsFile.mockImplementation(async (_agentId: string, path: string) => {+ const detail = details[path];+ if (!detail) throw new Error(`Missing detail for ${path}`);+ return detail;+ });++ root = createRoot(container);+ await act(async () => {+ root?.render(+ <QueryClientProvider client={queryClient}>+ <PromptsTab+ agent={props.agent ?? makeAgent()}+ companyId={props.companyId ?? "company-1"}+ onDirtyChange={props.onDirtyChange ?? vi.fn()}+ onSaveActionChange={props.onSaveActionChange ?? ((next) => { saveAction = next; })}+ onCancelActionChange={props.onCancelActionChange ?? vi.fn()}+ onSavingChange={props.onSavingChange ?? vi.fn()}+ />+ </QueryClientProvider>,+ );+ });+ await flushReact();+ }++ it("uses server markdown metadata for extensionless files and saves MarkdownEditor drafts", async () => {+ const summary = makeSummary("AGENTS", "AGENTS", {+ language: "markdown",+ markdown: true,+ });+ await renderPromptsTab(+ makeBundle("AGENTS", [summary]),+ { AGENTS: makeDetail(summary, "# Current") },+ );++ const editor = await waitFor(() => {+ const candidate = container.querySelector<HTMLTextAreaElement>('[data-testid="markdown-editor"]');+ expect(candidate).not.toBeNull();+ return candidate!;+ });+ expect(markdownEditorRenderMock).toHaveBeenLastCalledWith(expect.objectContaining({+ contentClassName: expect.not.stringContaining("font-mono"),+ hasImageUploadHandler: true,+ value: "# Current",+ }));++ await act(async () => {+ setNativeValue(editor, "# Updated");+ });+ await waitFor(() => {+ expect(saveAction).toEqual(expect.any(Function));+ });++ saveAction?.();+ await waitFor(() => {+ expect(mockAgentsApi.saveInstructionsFile).toHaveBeenCalledWith(+ "agent-1",+ {+ path: "AGENTS",+ content: "# Updated",+ clearLegacyPromptTemplate: false,+ },+ "company-1",+ );+ });+ });++ it("uses the Markdown editor for pending new .md files before server metadata exists", async () => {+ const summary = makeSummary("settings.json", "settings.json", {+ language: "json",+ markdown: false,+ });+ await renderPromptsTab(+ makeBundle("settings.json", [summary]),+ { "settings.json": makeDetail(summary, "{\n \"ok\": true\n}") },+ );++ await waitFor(() => {+ expect(container.querySelector<HTMLTextAreaElement>('textarea[placeholder="File contents"]')).not.toBeNull();+ });++ await act(async () => {+ buttonByText(container, "+").click();+ });+ await flushReact();+ const input = container.querySelector<HTMLInputElement>('input[placeholder="TOOLS.md"]');+ expect(input).not.toBeNull();++ await act(async () => {+ setNativeValue(input!, "notes.md");+ buttonByText(container, "Create").click();+ });++ await waitFor(() => {+ expect(container.querySelector('[data-testid="markdown-editor"]')).not.toBeNull();+ });+ expect(mockAgentsApi.instructionsFile).not.toHaveBeenCalledWith("agent-1", "notes.md", "company-1");+ });++ it("falls back to extension detection for existing .md files when metadata is missing", async () => {+ const summary = makeSummary("FALLBACK.md", "FALLBACK.md", {+ language: "text",+ markdown: undefined,+ });+ await renderPromptsTab(+ makeBundle("FALLBACK.md", [summary]),+ { "FALLBACK.md": makeDetail(summary, "# Fallback", { markdown: undefined }) },+ );++ await waitFor(() => {+ expect(container.querySelector("[data-testid=\"markdown-editor\"]")).not.toBeNull();+ expect(markdownEditorRenderMock).toHaveBeenLastCalledWith(expect.objectContaining({+ value: "# Fallback",+ }));+ });+ });++ it("keeps the raw textarea when server metadata marks an .md file as non-Markdown", async () => {+ const summary = makeSummary("NOTES.md", "NOTES.md", {+ language: "text",+ markdown: false,+ });+ await renderPromptsTab(+ makeBundle("NOTES.md", [summary]),+ { "NOTES.md": makeDetail(summary, "raw instructions") },+ );++ await waitFor(() => {+ expect(container.querySelector('[data-testid="markdown-editor"]')).toBeNull();+ expect(container.querySelector<HTMLTextAreaElement>('textarea[placeholder="File contents"]')?.value).toBe("raw instructions");+ });+ });+});diff --git a/ui/src/pages/AgentDetail.tsx b/ui/src/pages/AgentDetail.tsxindex 6006c3152c..0a8720d52d 100644--- a/ui/src/pages/AgentDetail.tsx+++ b/ui/src/pages/AgentDetail.tsx@@ -179,6 +179,17 @@ function isMarkdown(pathValue: string) {return pathValue.toLowerCase().endsWith(".md");}+function shouldUseMarkdownInstructionsEditor(input: {+ selectedFileExists: boolean;+ selectedPath: string;+ detail?: { markdown?: boolean } | null;+ summary?: { markdown?: boolean } | null;+}) {+ const metadataMarkdown = input.detail?.markdown ?? input.summary?.markdown;+ if (typeof metadataMarkdown === "boolean") return metadataMarkdown;+ return isMarkdown(input.selectedPath);+}+function formatEnvForDisplay(envValue: unknown, censorUsernameInLogs: boolean): string {const env = asRecord(envValue);if (!env) return "<unable-to-parse>";@@ -1951,7 +1962,7 @@ function ConfigurationTab({/* ---- Prompts Tab ---- */-function PromptsTab({+export function PromptsTab({agent,companyId,onDirtyChange,@@ -2190,6 +2201,12 @@ function PromptsTab({const currentContent = selectedFileExists ? (selectedFileDetail?.content ?? "") : "";const displayValue = draft ?? currentContent;+ const useMarkdownEditor = shouldUseMarkdownInstructionsEditor({+ selectedFileExists,+ selectedPath: selectedOrEntryFile,+ detail: selectedFileDetail,+ summary: selectedFileSummary,+ });const bundleDirty = Boolean(bundleDraft &&(@@ -2664,14 +2681,14 @@ function PromptsTab({{selectedFileExists && fileLoading && !selectedFileDetail ? (<PromptEditorSkeleton />- ) : isMarkdown(selectedOrEntryFile) ? (+ ) : useMarkdownEditor ? (<MarkdownEditorkey={selectedOrEntryFile}value={displayValue}onChange={(value) => setDraft(value ?? "")}placeholder="# Agent instructions"className="min-w-0 overflow-hidden"- contentClassName="min-h-(--sz-420px) max-w-full break-words text-sm font-mono"+ contentClassName="min-h-(--sz-420px) max-w-full break-words text-sm leading-7"imageUploadHandler={async (file) => {const namespace = `agents/${agent.id}/instructions/${selectedOrEntryFile.replaceAll("/", "-")}`;const asset = await uploadMarkdownImage.mutateAsync({ file, namespace });