Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: keep imported system messages as system through save and load (#17052)

DimitriChrysafisa7ee424d3cfd
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 066bda7e8f2..d66658adb9a 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -1723,6 +1723,19 @@ function serializeAssistantReplayMessages(
return messages;
}
+/** Strict templates (Qwen3.5) reject a second system turn; the backend joins system parts with "\n\n", so merging is byte-identical there. */
+function prependSystemPrompt<T extends { role: string; content: unknown }>(
+ messages: T[],
+ text: string,
+): void {
+ const first = messages[0];
+ if (first?.role === "system" && typeof first.content === "string") {
+ messages[0] = { ...first, content: `${text}\n\n${first.content}` };
+ return;
+ }
+ messages.unshift({ role: "system", content: text } as T);
+}
+
function toOpenAIMessages(
message: RunMessage,
includeReasoningContent = false,
@@ -2216,10 +2229,7 @@ export async function buildLocalTokenCountHistory(
systemPrompt: safeSystemPrompt,
});
if (combinedSystemPrompt) {
- outboundMessages.unshift({
- role: "system",
- content: combinedSystemPrompt,
- });
+ prependSystemPrompt(outboundMessages, combinedSystemPrompt);
}
return {
@@ -5415,10 +5425,7 @@ export function createOpenAIStreamAdapter(
{ agentsMd: true },
);
if (combinedSystemPrompt) {
- outboundMessages.unshift({
- role: "system",
- content: combinedSystemPrompt,
- });
+ prependSystemPrompt(outboundMessages, combinedSystemPrompt);
}
let disabledToolGuard: string | null = null;
const disabledToolGuardProviderType = externalProvider?.providerType;
diff --git a/studio/frontend/src/features/chat/runtime-provider.tsx b/studio/frontend/src/features/chat/runtime-provider.tsx
index 18894b6817c..4cff1c2700e 100644
--- a/studio/frontend/src/features/chat/runtime-provider.tsx
+++ b/studio/frontend/src/features/chat/runtime-provider.tsx
@@ -1415,6 +1415,27 @@ function toThreadMessage(m: MessageRecord): ThreadMessage {
},
};
}
+ if (m.role === "system") {
+ const textPart = {
+ type: "text" as const,
+ text: content
+ .filter(
+ (part): part is Extract<typeof part, { type: "text" }> =>
+ part.type === "text",
+ )
+ .map((part) => part.text)
+ .join("\n"),
+ };
+ return {
+ id: m.id,
+ createdAt: new Date(m.createdAt),
+ role: "system" as const,
+ content: [textPart],
+ metadata: {
+ custom: (m.metadata as Record<string, unknown>) ?? {},
+ },
+ };
+ }
const custom = (m.metadata as Record<string, unknown>) ?? {};
const savedTiming = custom.timing as
| import("@assistant-ui/react").MessageTiming
diff --git a/studio/frontend/src/features/chat/utils/chat-import.ts b/studio/frontend/src/features/chat/utils/chat-import.ts
index 8cd1d271d46..21b8dc5c1b0 100644
--- a/studio/frontend/src/features/chat/utils/chat-import.ts
+++ b/studio/frontend/src/features/chat/utils/chat-import.ts
@@ -272,11 +272,11 @@ function markdownToRecords(
if (!content.trim()) continue;
const normalizedRole = role.trim().toLowerCase();
const validRole =
- normalizedRole === "user" ||
- normalizedRole === "assistant" ||
- normalizedRole === "system"
- ? normalizedRole
- : normalizedRole.length > 0
+ normalizedRole === "developer"
+ ? "system"
+ : normalizedRole === "user" ||
+ normalizedRole === "assistant" ||
+ normalizedRole === "system"
? normalizedRole
: "user";
const id = crypto.randomUUID();
diff --git a/studio/frontend/src/features/chat/utils/delete-thread-message.ts b/studio/frontend/src/features/chat/utils/delete-thread-message.ts
index 81b3cde3fde..72578a2e6dd 100644
--- a/studio/frontend/src/features/chat/utils/delete-thread-message.ts
+++ b/studio/frontend/src/features/chat/utils/delete-thread-message.ts
@@ -64,6 +64,21 @@ export function exportedItemToRecord(
createdAt: toEpochMillis(message.createdAt),
};
}
+ if (message.role === "system") {
+ const custom = message.metadata?.custom;
+ return {
+ id: message.id,
+ threadId,
+ parentId: parentId ?? null,
+ role: "system",
+ content: content as Extract<
+ ThreadMessage,
+ { role: "system" }
+ >["content"],
+ ...(custom && Object.keys(custom).length > 0 && { metadata: custom }),
+ createdAt: toEpochMillis(message.createdAt),
+ };
+ }
const custom = (message.metadata?.custom ?? {}) as Record<string, unknown>;
return {
id: message.id,
diff --git a/studio/frontend/src/features/chat/utils/refresh-context-usage.ts b/studio/frontend/src/features/chat/utils/refresh-context-usage.ts
index 48905c654e2..6d137eef5df 100644
--- a/studio/frontend/src/features/chat/utils/refresh-context-usage.ts
+++ b/studio/frontend/src/features/chat/utils/refresh-context-usage.ts
@@ -58,6 +58,26 @@ function storedMessageToRunMessage(record: MessageRecord): ThreadMessage {
};
}
+ if (record.role === "system") {
+ const textPart = {
+ type: "text" as const,
+ text: content
+ .filter(
+ (part): part is Extract<typeof part, { type: "text" }> =>
+ part.type === "text",
+ )
+ .map((part) => part.text)
+ .join("\n"),
+ };
+ return {
+ id: record.id,
+ createdAt: new Date(record.createdAt),
+ role: "system",
+ content: [textPart],
+ metadata: { custom: (record.metadata as Record<string, unknown>) ?? {} },
+ };
+ }
+
const custom = (record.metadata as Record<string, unknown>) ?? {};
const savedTiming = custom.timing as
| import("@assistant-ui/react").MessageTiming
diff --git a/studio/frontend/tests/chat-system-role.test.ts b/studio/frontend/tests/chat-system-role.test.ts
new file mode 100644
index 00000000000..77e863c5aa1
--- /dev/null
+++ b/studio/frontend/tests/chat-system-role.test.ts
@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Chat importers keep system records (backup import downgrades them on purpose); every converter must too.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import vm from "node:vm";
+import ts from "@typescript/typescript6";
+import type { ThreadMessage } from "@assistant-ui/react";
+
+import type { MessageRecord } from "../src/features/chat/types.ts";
+import { readSrc } from "./helpers/kit.ts";
+
+const PROVIDER = readSrc("features/chat/runtime-provider.tsx");
+const SYNC = readSrc("features/chat/utils/delete-thread-message.ts");
+const REFRESH = readSrc("features/chat/utils/refresh-context-usage.ts");
+const IMPORT = readSrc("features/chat/utils/chat-import.ts");
+const ADAPTER = readSrc("features/chat/api/chat-adapter.ts");
+
+function slice(source: string, startMarker: string, endMarker: string): string {
+ const start = source.indexOf(startMarker);
+ const end = source.indexOf(endMarker, start);
+ assert.notEqual(start, -1, `${startMarker} must exist`);
+ assert.notEqual(end, -1, `${endMarker} must exist`);
+ return source.slice(start, end);
+}
+
+function run<T>(source: string, exportLine: string, context: Record<string, unknown>): T {
+ const unexported = source.replace(/\bexport\s+(?=(async\s+)?function)/g, "");
+ const javascript = ts.transpileModule(`${unexported}\n${exportLine}`, {
+ compilerOptions: { module: ts.ModuleKind.None, target: ts.ScriptTarget.ES2022 },
+ }).outputText;
+ vm.runInNewContext(javascript, context);
+ return context.__fn as T;
+}
+
+function loadToThreadMessage(): (m: MessageRecord) => ThreadMessage {
+ const source = slice(
+ PROVIDER,
+ "function toThreadMessage(",
+ "type GenerationRecovery",
+ );
+ return run(source, "globalThis.__fn = toThreadMessage;", {
+ cloneContent: (content: unknown) => (Array.isArray(content) ? [...content] : []),
+ cloneAttachments: () => [],
+ restoredAssistantStatus: () => ({ type: "complete", reason: "stop" }),
+ generationIsCorroboratedLive: () => false,
+ Date,
+ });
+}
+
+function loadExportedItemToRecord(): (
+ threadId: string,
+ parentId: string | null,
+ message: ThreadMessage,
+) => MessageRecord {
+ const source = slice(
+ SYNC,
+ "function snapshotContent(",
+ "async function withStoredResearchMessages",
+ );
+ return run(source, "globalThis.__fn = exportedItemToRecord;", { Date });
+}
+
+function loadStoredMessageToRunMessage(): (record: MessageRecord) => ThreadMessage {
+ const source = slice(
+ REFRESH,
+ "function storedMessageToRunMessage(",
+ "function foldHash(",
+ );
+ return run(source, "globalThis.__fn = storedMessageToRunMessage;", {
+ structuredClone,
+ Date,
+ });
+}
+
+function loadMarkdownToRecords(): (
+ messages: Array<{ role: string; content: string }>,
+ threadId: string,
+ baseTs: number,
+) => MessageRecord[] {
+ const source = slice(
+ IMPORT,
+ "function markdownToRecords(",
+ "function csvToRecords(",
+ );
+ return run(source, "globalThis.__fn = markdownToRecords;", { crypto });
+}
+
+const SYSTEM_RECORD: MessageRecord = {
+ id: "sys-1",
+ threadId: "t1",
+ parentId: null,
+ role: "system",
+ content: [{ type: "text", text: "Be terse." }],
+ metadata: {},
+ createdAt: 1_700_000_000_000,
+};
+
+test("a stored system message loads as a system ThreadMessage, not assistant", () => {
+ const toThreadMessage = loadToThreadMessage();
+ const message = toThreadMessage(SYSTEM_RECORD);
+ assert.equal(message.role, "system");
+ const parts = message.content as readonly { type: string; text: string }[];
+ assert.equal(parts.length, 1);
+ assert.equal(parts[0].text, "Be terse.");
+});
+
+test("saving a system ThreadMessage writes the system role back", () => {
+ const exportedItemToRecord = loadExportedItemToRecord();
+ const record = exportedItemToRecord("t1", null, {
+ id: "sys-1",
+ role: "system",
+ content: [{ type: "text", text: "Be terse." }],
+ createdAt: new Date(1_700_000_000_000),
+ metadata: { custom: {} },
+ });
+ assert.equal(record.role, "system");
+ assert.equal(record.createdAt, 1_700_000_000_000);
+});
+
+test("a system record survives a load-then-autosave round trip unchanged", () => {
+ const toThreadMessage = loadToThreadMessage();
+ const exportedItemToRecord = loadExportedItemToRecord();
+ const roundTripped = exportedItemToRecord(
+ "t1",
+ null,
+ toThreadMessage(SYSTEM_RECORD),
+ );
+ assert.equal(roundTripped.role, "system");
+ assert.equal(roundTripped.createdAt, 1_700_000_000_000);
+ const parts = roundTripped.content as unknown as readonly { text: string }[];
+ assert.equal(parts[0].text, "Be terse.");
+});
+
+test("user and assistant roles still map to themselves", () => {
+ const toThreadMessage = loadToThreadMessage();
+ const exportedItemToRecord = loadExportedItemToRecord();
+ for (const role of ["user", "assistant"] as const) {
+ const record = { ...SYSTEM_RECORD, role };
+ assert.equal(toThreadMessage(record).role, role);
+ assert.equal(
+ exportedItemToRecord("t1", null, toThreadMessage(record)).role,
+ role,
+ );
+ }
+});
+
+test("the token-count reader keeps a stored system record as system", () => {
+ const storedMessageToRunMessage = loadStoredMessageToRunMessage();
+ const message = storedMessageToRunMessage(SYSTEM_RECORD);
+ assert.equal(message.role, "system");
+ const parts = message.content as readonly { type: string; text: string }[];
+ assert.equal(parts.length, 1);
+ assert.equal(parts[0].text, "Be terse.");
+});
+
+test("a markdown Developer heading imports as a system record", () => {
+ const markdownToRecords = loadMarkdownToRecords();
+ const records = markdownToRecords(
+ [
+ { role: "Developer", content: "Be terse." },
+ { role: "User", content: "Hi" },
+ ],
+ "t1",
+ 0,
+ );
+ assert.equal(records[0].role, "system");
+ assert.equal(records[1].role, "user");
+});
+
+test("an unrecognized markdown role imports as user, not a folded assistant", () => {
+ const markdownToRecords = loadMarkdownToRecords();
+ const records = markdownToRecords(
+ [{ role: "Helper", content: "Something" }],
+ "t1",
+ 0,
+ );
+ assert.equal(records[0].role, "user");
+});
+
+type Outbound = { role: string; content: unknown };
+const SECOND_SYSTEM_UNSHIFT =
+ /outboundMessages\.unshift\(\{\s*role: "system",\s*content: combinedSystemPrompt/;
+
+test("the Studio prompt merges into an imported leading system turn instead of adding a second", () => {
+ const prepend = run<(messages: Outbound[], text: string) => void>(
+ slice(
+ ADAPTER,
+ "function prependSystemPrompt",
+ "function toOpenAIMessages(",
+ ),
+ "globalThis.__fn = prependSystemPrompt;",
+ {},
+ );
+ const imported: Outbound[] = [
+ { role: "system", content: "Imported." },
+ { role: "user", content: "Hi" },
+ ];
+ prepend(imported, "Studio.");
+ assert.deepEqual(JSON.parse(JSON.stringify(imported)), [
+ { role: "system", content: "Studio.\n\nImported." },
+ { role: "user", content: "Hi" },
+ ]);
+ const plain: Outbound[] = [{ role: "user", content: "Hi" }];
+ prepend(plain, "Studio.");
+ assert.deepEqual(JSON.parse(JSON.stringify(plain)), [
+ { role: "system", content: "Studio." },
+ { role: "user", content: "Hi" },
+ ]);
+ assert.doesNotMatch(ADAPTER, SECOND_SYSTEM_UNSHIFT);
+});