@directus/api 33.0.0 → 33.1.0

package/dist/ai/chat/controllers/chat.post.js

@@ -13,7 +13,21 @@ export const aiChatPostHandler = async (req, res, _next) => {
     if (!parseResult.success) {
         throw new InvalidPayloadError({ reason: fromZodError(parseResult.error).message });
     }
-    const { provider, model, messages: rawMessages, tools: requestedTools, toolApprovals } = parseResult.data;
+    const { provider, model, messages: rawMessages, tools: requestedTools, toolApprovals, context } = parseResult.data;
+    const aiSettings = res.locals['ai'].settings;
+    const allowedModelsMap = {
+        openai: aiSettings.openaiAllowedModels,
+        anthropic: aiSettings.anthropicAllowedModels,
+        google: aiSettings.googleAllowedModels,
+    };
+    // For standard providers: null/empty = no models allowed, must be in list
+    // openai-compatible skips validation entirely
+    if (provider !== 'openai-compatible') {
+        const allowedModels = allowedModelsMap[provider];
+        if (!allowedModels || allowedModels.length === 0 || !allowedModels.includes(model)) {
+            throw new ForbiddenError({ reason: 'Model not allowed for this provider' });
+        }
+    }
     if (rawMessages.length === 0) {
         throw new InvalidPayloadError({ reason: `"messages" must not be empty` });
     }
@@ -33,12 +47,13 @@ export const aiChatPostHandler = async (req, res, _next) => {
     if (validationResult.success === false) {
         throw new InvalidPayloadError({ reason: validationResult.error.message });
     }
-    const stream = createUiStream(validationResult.data, {
+    const stream = await createUiStream(validationResult.data, {
         provider,
         model,
-        tools: tools,
-        apiKeys: res.locals['ai'].apiKeys,
+        tools,
+        aiSettings,
         systemPrompt: res.locals['ai'].systemPrompt,
+        ...(context && { context }),
         onUsage: (usage) => {
             res.write(`data: ${JSON.stringify({ type: 'data-usage', data: usage })}\n\n`);
         },

package/dist/ai/chat/lib/create-ui-stream.d.ts

@@ -1,15 +1,16 @@
+import type { ProviderType } from '@directus/ai';
 import { type LanguageModelUsage, type StreamTextResult, type Tool, type UIMessage } from 'ai';
+import { type AISettings } from '../../providers/index.js';
+import type { ChatContext } from '../models/chat-request.js';
 export interface CreateUiStreamOptions {
-    provider: 'openai' | 'anthropic';
+    provider: ProviderType;
     model: string;
     tools: {
         [x: string]: Tool;
     };
-    apiKeys: {
-        openai: string | null;
-        anthropic: string | null;
-    };
+    aiSettings: AISettings;
     systemPrompt?: string;
+    context?: ChatContext;
     onUsage?: (usage: Pick<LanguageModelUsage, 'inputTokens' | 'outputTokens' | 'totalTokens'>) => void | Promise<void>;
 }
-export declare const createUiStream: (messages: UIMessage[], { provider, model, tools, apiKeys, systemPrompt, onUsage }: CreateUiStreamOptions) => StreamTextResult<Record<string, Tool<any, any>>, any>;
+export declare const createUiStream: (messages: UIMessage[], { provider, model, tools, aiSettings, systemPrompt, context, onUsage }: CreateUiStreamOptions) => Promise<StreamTextResult<Record<string, Tool<any, any>>, any>>;

package/dist/ai/chat/lib/create-ui-stream.js

@@ -1,36 +1,39 @@
-import { createAnthropic } from '@ai-sdk/anthropic';
-import { createOpenAI } from '@ai-sdk/openai';
 import { ServiceUnavailableError } from '@directus/errors';
 import { convertToModelMessages, stepCountIs, streamText, } from 'ai';
+import { buildProviderConfigs, createAIProviderRegistry, getProviderOptions, } from '../../providers/index.js';
 import { SYSTEM_PROMPT } from '../constants/system-prompt.js';
-export const createUiStream = (messages, { provider, model, tools, apiKeys, systemPrompt, onUsage }) => {
-    if (apiKeys[provider] === null) {
+import { formatContextForSystemPrompt } from '../utils/format-context.js';
+export const createUiStream = async (messages, { provider, model, tools, aiSettings, systemPrompt, context, onUsage }) => {
+    const configs = buildProviderConfigs(aiSettings);
+    const providerConfig = configs.find((c) => c.type === provider);
+    if (!providerConfig) {
         throw new ServiceUnavailableError({ service: provider, reason: 'No API key configured for LLM provider' });
     }
-    let modelProvider;
-    if (provider === 'openai') {
-        modelProvider = createOpenAI({ apiKey: apiKeys.openai });
-    }
-    else if (provider === 'anthropic') {
-        modelProvider = createAnthropic({ apiKey: apiKeys.anthropic });
-    }
-    else {
-        throw new Error(`Unexpected provider given: "${provider}"`);
-    }
-    systemPrompt ||= SYSTEM_PROMPT;
+    const registry = createAIProviderRegistry(configs, aiSettings);
+    const baseSystemPrompt = systemPrompt || SYSTEM_PROMPT;
+    const contextBlock = context ? formatContextForSystemPrompt(context) : null;
+    const providerOptions = getProviderOptions(provider, model, aiSettings);
+    // Compute the full system prompt once to avoid re-computing on each step
+    const fullSystemPrompt = contextBlock ? baseSystemPrompt + contextBlock : baseSystemPrompt;
     const stream = streamText({
-        system: systemPrompt,
-        model: modelProvider(model),
-        messages: convertToModelMessages(messages),
+        system: baseSystemPrompt,
+        model: registry.languageModel(`${provider}:${model}`),
+        messages: await convertToModelMessages(messages),
         stopWhen: [stepCountIs(10)],
-        providerOptions: {
-            openai: {
-                reasoningSummary: 'auto',
-                store: false,
-                include: ['reasoning.encrypted_content'],
-            },
-        },
+        providerOptions,
         tools,
+        /**
+         * prepareStep is called before each AI step to prepare the system prompt.
+         * When context exists, we override the system prompt to include context attachments.
+         * This allows the initial system prompt to be simple while ensuring all steps
+         * (including tool continuation steps) receive the full context.
+         */
+        prepareStep: () => {
+            if (contextBlock) {
+                return { system: fullSystemPrompt };
+            }
+            return {};
+        },
         onFinish({ usage }) {
             if (onUsage) {
                 const { inputTokens, outputTokens, totalTokens } = usage;

package/dist/ai/chat/middleware/load-settings.js

@@ -4,15 +4,39 @@ export const loadSettings = async (_req, res, next) => {
     const service = new SettingsService({
         schema: await getSchema(),
     });
-    const { ai_openai_api_key, ai_anthropic_api_key, ai_system_prompt } = await service.readSingleton({
-        fields: ['ai_openai_api_key', 'ai_anthropic_api_key', 'ai_system_prompt'],
+    const settings = await service.readSingleton({
+        fields: [
+            'ai_openai_api_key',
+            'ai_anthropic_api_key',
+            'ai_google_api_key',
+            'ai_openai_compatible_api_key',
+            'ai_openai_compatible_base_url',
+            'ai_openai_compatible_name',
+            'ai_openai_compatible_models',
+            'ai_openai_compatible_headers',
+            'ai_openai_allowed_models',
+            'ai_anthropic_allowed_models',
+            'ai_google_allowed_models',
+            'ai_system_prompt',
+        ],
     });
+    const aiSettings = {
+        openaiApiKey: settings['ai_openai_api_key'] ?? null,
+        anthropicApiKey: settings['ai_anthropic_api_key'] ?? null,
+        googleApiKey: settings['ai_google_api_key'] ?? null,
+        openaiCompatibleApiKey: settings['ai_openai_compatible_api_key'] ?? null,
+        openaiCompatibleBaseUrl: settings['ai_openai_compatible_base_url'] ?? null,
+        openaiCompatibleName: settings['ai_openai_compatible_name'] ?? null,
+        openaiCompatibleModels: settings['ai_openai_compatible_models'] ?? null,
+        openaiCompatibleHeaders: settings['ai_openai_compatible_headers'] ?? null,
+        openaiAllowedModels: settings['ai_openai_allowed_models'] ?? null,
+        anthropicAllowedModels: settings['ai_anthropic_allowed_models'] ?? null,
+        googleAllowedModels: settings['ai_google_allowed_models'] ?? null,
+        systemPrompt: settings['ai_system_prompt'] ?? null,
+    };
     res.locals['ai'] = {
-        apiKeys: {
-            openai: ai_openai_api_key,
-            anthropic: ai_anthropic_api_key,
-        },
-        systemPrompt: ai_system_prompt,
+        settings: aiSettings,
+        systemPrompt: settings['ai_system_prompt'],
     };
     return next();
 };

package/dist/ai/chat/models/chat-request.d.ts

@@ -12,12 +12,103 @@ export declare const ToolApprovalMode: z.ZodEnum<{
     disabled: "disabled";
 }>;
 export type ToolApprovalMode = z.infer<typeof ToolApprovalMode>;
+export declare const ContextAttachment: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"item">;
+    display: z.ZodString;
+    data: z.ZodObject<{
+        collection: z.ZodString;
+        key: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strip>;
+    snapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"visual-element">;
+    display: z.ZodString;
+    data: z.ZodObject<{
+        key: z.ZodString;
+        collection: z.ZodString;
+        item: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        rect: z.ZodOptional<z.ZodObject<{
+            top: z.ZodNumber;
+            left: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    snapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"prompt">;
+    display: z.ZodString;
+    data: z.ZodObject<{
+        text: z.ZodString;
+        prompt: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        values: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>;
+    snapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>], "type">;
+export type ContextAttachment = z.infer<typeof ContextAttachment>;
+export declare const PageContext: z.ZodObject<{
+    path: z.ZodString;
+    collection: z.ZodOptional<z.ZodString>;
+    item: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    module: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PageContext = z.infer<typeof PageContext>;
+export declare const ChatContext: z.ZodObject<{
+    attachments: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"item">;
+        display: z.ZodString;
+        data: z.ZodObject<{
+            collection: z.ZodString;
+            key: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        }, z.core.$strip>;
+        snapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"visual-element">;
+        display: z.ZodString;
+        data: z.ZodObject<{
+            key: z.ZodString;
+            collection: z.ZodString;
+            item: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            rect: z.ZodOptional<z.ZodObject<{
+                top: z.ZodNumber;
+                left: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        snapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"prompt">;
+        display: z.ZodString;
+        data: z.ZodObject<{
+            text: z.ZodString;
+            prompt: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            values: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strip>;
+        snapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>], "type">>>;
+    page: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        collection: z.ZodOptional<z.ZodString>;
+        item: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        module: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ChatContext = z.infer<typeof ChatContext>;
 export declare const ChatRequest: z.ZodIntersection<z.ZodDiscriminatedUnion<[z.ZodObject<{
     provider: z.ZodLiteral<"openai">;
-    model: z.ZodUnion<readonly [z.ZodLiteral<"gpt-5">, z.ZodLiteral<"gpt-5-nano">, z.ZodLiteral<"gpt-5-mini">, z.ZodLiteral<"gpt-5-pro">]>;
+    model: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     provider: z.ZodLiteral<"anthropic">;
-    model: z.ZodUnion<readonly [z.ZodLiteral<"claude-sonnet-4-5">, z.ZodLiteral<"claude-haiku-4-5">, z.ZodLiteral<"claude-opus-4-1">]>;
+    model: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    provider: z.ZodLiteral<"google">;
+    model: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    provider: z.ZodLiteral<"openai-compatible">;
+    model: z.ZodString;
 }, z.core.$strip>], "provider">, z.ZodObject<{
     tools: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         name: z.ZodString;
@@ -30,5 +121,47 @@ export declare const ChatRequest: z.ZodIntersection<z.ZodDiscriminatedUnion<[z.Z
         ask: "ask";
         disabled: "disabled";
     }>>>;
+    context: z.ZodOptional<z.ZodObject<{
+        attachments: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"item">;
+            display: z.ZodString;
+            data: z.ZodObject<{
+                collection: z.ZodString;
+                key: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            }, z.core.$strip>;
+            snapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"visual-element">;
+            display: z.ZodString;
+            data: z.ZodObject<{
+                key: z.ZodString;
+                collection: z.ZodString;
+                item: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+                fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                rect: z.ZodOptional<z.ZodObject<{
+                    top: z.ZodNumber;
+                    left: z.ZodNumber;
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            snapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"prompt">;
+            display: z.ZodString;
+            data: z.ZodObject<{
+                text: z.ZodString;
+                prompt: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                values: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, z.core.$strip>;
+            snapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>], "type">>>;
+        page: z.ZodOptional<z.ZodObject<{
+            path: z.ZodString;
+            collection: z.ZodOptional<z.ZodString>;
+            item: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            module: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>>;
 export type ChatRequest = z.infer<typeof ChatRequest>;

package/dist/ai/chat/models/chat-request.js

@@ -1,7 +1,7 @@
 import {} from 'ai';
 import { z } from 'zod';
 import { parseJsonSchema7 } from '../utils/parse-json-schema-7.js';
-import { ProviderAnthropic, ProviderOpenAi } from './providers.js';
+import { ProviderAnthropic, ProviderGoogle, ProviderOpenAi, ProviderOpenAiCompatible } from './providers.js';
 export const ChatRequestTool = z.union([
     z.string(),
     z.object({
@@ -19,8 +19,62 @@ export const ChatRequestTool = z.union([
     }),
 ]);
 export const ToolApprovalMode = z.enum(['always', 'ask', 'disabled']);
-export const ChatRequest = z.intersection(z.discriminatedUnion('provider', [ProviderOpenAi, ProviderAnthropic]), z.object({
+const ItemContextData = z.object({
+    collection: z.string(),
+    key: z.union([z.string(), z.number()]),
+});
+const VisualElementContextData = z.object({
+    key: z.string(),
+    collection: z.string(),
+    item: z.union([z.string(), z.number()]),
+    fields: z.array(z.string()).optional(),
+    rect: z
+        .object({
+        top: z.number(),
+        left: z.number(),
+        width: z.number(),
+        height: z.number(),
+    })
+        .optional(),
+});
+const PromptContextData = z.object({
+    text: z.string(),
+    prompt: z.record(z.string(), z.unknown()),
+    values: z.record(z.string(), z.string()),
+});
+export const ContextAttachment = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('item'),
+        display: z.string(),
+        data: ItemContextData,
+        snapshot: z.record(z.string(), z.unknown()),
+    }),
+    z.object({
+        type: z.literal('visual-element'),
+        display: z.string(),
+        data: VisualElementContextData,
+        snapshot: z.record(z.string(), z.unknown()),
+    }),
+    z.object({
+        type: z.literal('prompt'),
+        display: z.string(),
+        data: PromptContextData,
+        snapshot: z.record(z.string(), z.unknown()),
+    }),
+]);
+export const PageContext = z.object({
+    path: z.string(),
+    collection: z.string().optional(),
+    item: z.union([z.string(), z.number()]).optional(),
+    module: z.string().optional(),
+});
+export const ChatContext = z.object({
+    attachments: z.array(ContextAttachment).max(10).optional(),
+    page: PageContext.optional(),
+});
+export const ChatRequest = z.intersection(z.discriminatedUnion('provider', [ProviderOpenAi, ProviderAnthropic, ProviderGoogle, ProviderOpenAiCompatible]), z.object({
     tools: z.array(ChatRequestTool),
     messages: z.array(z.looseObject({})),
     toolApprovals: z.record(z.string(), ToolApprovalMode).optional(),
+    context: ChatContext.optional(),
 }));

package/dist/ai/chat/models/providers.d.ts

@@ -1,9 +1,23 @@
 import { z } from 'zod';
+export declare const ProviderTypeSchema: z.ZodEnum<{
+    openai: "openai";
+    anthropic: "anthropic";
+    google: "google";
+    "openai-compatible": "openai-compatible";
+}>;
 export declare const ProviderOpenAi: z.ZodObject<{
     provider: z.ZodLiteral<"openai">;
-    model: z.ZodUnion<readonly [z.ZodLiteral<"gpt-5">, z.ZodLiteral<"gpt-5-nano">, z.ZodLiteral<"gpt-5-mini">, z.ZodLiteral<"gpt-5-pro">]>;
+    model: z.ZodString;
 }, z.core.$strip>;
 export declare const ProviderAnthropic: z.ZodObject<{
     provider: z.ZodLiteral<"anthropic">;
-    model: z.ZodUnion<readonly [z.ZodLiteral<"claude-sonnet-4-5">, z.ZodLiteral<"claude-haiku-4-5">, z.ZodLiteral<"claude-opus-4-1">]>;
+    model: z.ZodString;
+}, z.core.$strip>;
+export declare const ProviderGoogle: z.ZodObject<{
+    provider: z.ZodLiteral<"google">;
+    model: z.ZodString;
+}, z.core.$strip>;
+export declare const ProviderOpenAiCompatible: z.ZodObject<{
+    provider: z.ZodLiteral<"openai-compatible">;
+    model: z.ZodString;
 }, z.core.$strip>;

package/dist/ai/chat/models/providers.js

@@ -1,9 +1,23 @@
 import { z } from 'zod';
+export const ProviderTypeSchema = z.enum([
+    'openai',
+    'anthropic',
+    'google',
+    'openai-compatible',
+]);
 export const ProviderOpenAi = z.object({
     provider: z.literal('openai'),
-    model: z.union([z.literal('gpt-5'), z.literal('gpt-5-nano'), z.literal('gpt-5-mini'), z.literal('gpt-5-pro')]),
+    model: z.string(),
 });
 export const ProviderAnthropic = z.object({
     provider: z.literal('anthropic'),
-    model: z.union([z.literal('claude-sonnet-4-5'), z.literal('claude-haiku-4-5'), z.literal('claude-opus-4-1')]),
+    model: z.string(),
+});
+export const ProviderGoogle = z.object({
+    provider: z.literal('google'),
+    model: z.string(),
+});
+export const ProviderOpenAiCompatible = z.object({
+    provider: z.literal('openai-compatible'),
+    model: z.string(),
 });

package/dist/ai/chat/utils/chat-request-tool-to-ai-sdk-tool.js

@@ -1,6 +1,6 @@
 import { InvalidPayloadError } from '@directus/errors';
 import {} from '@directus/types';
-import { jsonSchema, tool } from 'ai';
+import { jsonSchema, tool, zodSchema } from 'ai';
 import { fromZodError } from 'zod-validation-error';
 import { ALL_TOOLS } from '../../tools/index.js';
 export const chatRequestToolToAiSdkTool = ({ chatRequestTool, accountability, schema, toolApprovals, }) => {
@@ -13,10 +13,10 @@ export const chatRequestToolToAiSdkTool = ({ chatRequestTool, accountability, sc
         // Default to 'ask' (needs approval) if not specified
         const approvalMode = toolApprovals?.[chatRequestTool] ?? 'ask';
         const needsApproval = approvalMode !== 'always';
+        const inputSchema = zodSchema(directusTool.inputSchema);
         return tool({
-            name: directusTool.name,
             description: directusTool.description,
-            inputSchema: directusTool.inputSchema,
+            inputSchema,
             needsApproval,
             execute: async (rawArgs) => {
                 const { error, data: args } = directusTool.validateSchema?.safeParse(rawArgs) ?? {
@@ -31,7 +31,6 @@ export const chatRequestToolToAiSdkTool = ({ chatRequestTool, accountability, sc
     }
     // Local/client-side tool (schema only, executed on client)
     return tool({
-        name: chatRequestTool.name,
         description: chatRequestTool.description,
         inputSchema: jsonSchema(chatRequestTool.inputSchema),
     });

package/dist/ai/chat/utils/format-context.d.ts

@@ -0,0 +1,5 @@
+import type { ChatContext } from '../models/chat-request.js';
+/**
+ * Format context for appending to system prompt
+ */
+export declare function formatContextForSystemPrompt(context: ChatContext): string;

package/dist/ai/chat/utils/format-context.js

@@ -0,0 +1,122 @@
+function escapeAngleBrackets(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+function groupAttachments(attachments) {
+    const groups = { visualElements: [], prompts: [], items: [] };
+    for (const att of attachments) {
+        switch (att.type) {
+            case 'visual-element':
+                groups.visualElements.push(att);
+                break;
+            case 'prompt':
+                groups.prompts.push(att);
+                break;
+            case 'item':
+                groups.items.push(att);
+                break;
+        }
+    }
+    return groups;
+}
+function formatVisualElement(att) {
+    const fields = att.data.fields?.length ? att.data.fields.map((f) => escapeAngleBrackets(f)).join(', ') : 'all';
+    const collection = escapeAngleBrackets(String(att.data.collection));
+    const item = escapeAngleBrackets(String(att.data.item));
+    const display = escapeAngleBrackets(att.display);
+    return `### ${collection}/${item} — "${display}"
+Editable fields: ${fields}
+\`\`\`json
+${escapeAngleBrackets(JSON.stringify(att.snapshot, null, 2))}
+\`\`\``;
+}
+function formatPrompt(att) {
+    const snapshot = att.snapshot;
+    const lines = [];
+    const display = escapeAngleBrackets(att.display);
+    if (snapshot.text) {
+        lines.push(escapeAngleBrackets(snapshot.text));
+    }
+    if (snapshot.messages?.length) {
+        lines.push('\n### Example Exchange');
+        for (const msg of snapshot.messages) {
+            const role = escapeAngleBrackets(msg.role);
+            const text = escapeAngleBrackets(msg.text);
+            lines.push(`**${role}**: ${text}`);
+        }
+    }
+    return `### ${display}\n${lines.join('\n')}`;
+}
+function formatItem(att) {
+    const display = escapeAngleBrackets(att.display);
+    const collectionLabel = att.data.collection ? ` (${escapeAngleBrackets(att.data.collection)})` : '';
+    const keyLabel = ` — key: ${escapeAngleBrackets(String(att.data.key))}`;
+    const collection = att.data.collection ? escapeAngleBrackets(att.data.collection) : '';
+    const updateHint = att.data.collection
+        ? `\nTo update this item, use the items tool with: collection="${collection}", keys=["${escapeAngleBrackets(String(att.data.key))}"], action="update"`
+        : '\nUse the items tool to update this item.';
+    return `[Item: ${display}${collectionLabel}${keyLabel}]${updateHint}\n${escapeAngleBrackets(JSON.stringify(att.snapshot, null, 2))}`;
+}
+/**
+ * Format context for appending to system prompt
+ */
+export function formatContextForSystemPrompt(context) {
+    const attachments = context.attachments ?? [];
+    const groups = groupAttachments(attachments);
+    const parts = [];
+    // 1. Custom instructions (prompts) - highest priority, placed first
+    if (groups.prompts.length > 0) {
+        const promptBlocks = groups.prompts.map(formatPrompt).join('\n\n');
+        parts.push(`<custom_instructions>
+The user has applied the following prompt(s) to guide your behavior:
+
+${promptBlocks}
+</custom_instructions>`);
+    }
+    // 2. User context (current page + items)
+    const sections = [];
+    const now = new Date();
+    sections.push(`## Current Date\n${now.toISOString().split('T')[0]}`);
+    if (context.page) {
+        const page = context.page;
+        const pageLines = [`Path: ${escapeAngleBrackets(String(page.path))}`];
+        if (page.collection)
+            pageLines.push(`Collection: ${escapeAngleBrackets(String(page.collection))}`);
+        if (page.item !== undefined)
+            pageLines.push(`Item: ${escapeAngleBrackets(String(page.item))}`);
+        if (page.module)
+            pageLines.push(`Module: ${escapeAngleBrackets(String(page.module))}`);
+        sections.push(`## Current Page\n${pageLines.join('\n')}`);
+    }
+    if (groups.items.length > 0) {
+        const itemLines = groups.items.map(formatItem).join('\n\n');
+        sections.push(`## User-Added Context
+The user has attached these items as reference for their request.
+All root-level fields the user has access to are shown below — use these exact field names when updating.
+Use the items tool to fetch additional fields or update items when asked.
+
+${itemLines}`);
+    }
+    if (sections.length > 0) {
+        parts.push(`<user_context>\n${sections.join('\n\n')}\n</user_context>`);
+    }
+    // 3. Visual editing context
+    if (groups.visualElements.length > 0) {
+        const elementLines = groups.visualElements.map(formatVisualElement).join('\n\n');
+        parts.push(`<visual_editing>
+## Selected Elements
+The user selected these elements for editing in the visual editor.
+
+${elementLines}
+</visual_editing>`);
+    }
+    // 4. Attachment rules (only if any attachments exist)
+    if (attachments.length > 0) {
+        parts.push(`## Attachment Rules
+- User-added attachments have HIGHER PRIORITY than page context.
+- To modify attached items, ALWAYS use the items tool with action: 'update'. NEVER use form-values tools for attached items.
+- form-values tools ONLY affect the currently open page form, which may be a DIFFERENT item than what the user attached.`);
+    }
+    if (parts.length === 0)
+        return '';
+    return '\n\n' + parts.join('\n\n');
+}