@vertesia/ui 1.5.0-dev.20260717.131047Z → 1.5.0-dev.20260725.083715Z

package/src/features/store/objects/components/DocumentIcon.tsx

@@ -103,7 +103,7 @@ export function DocumentIcon({
                 <Button
                     variant="ghost"
                     size="sm"
-                    title="Preivew Object"
+                    title="Preview Object"
                     onClick={(e) => {
                         e.stopPropagation();
                         previewObject?.(document.id);

package/src/features/store/objects/components/TextEditorPanel.test.tsx

@@ -0,0 +1,48 @@
+/** @vitest-environment jsdom */
+
+import { render, screen } from '@testing-library/react';
+import type { ContentObject } from '@vertesia/common';
+import { describe, expect, it, vi } from 'vitest';
+import { I18nProvider } from '../../../../i18n/index.js';
+import { TextEditorPanel } from './TextEditorPanel.js';
+
+const mocks = vi.hoisted(() => ({
+    navigate: vi.fn(),
+    update: vi.fn(),
+}));
+
+vi.mock('@vertesia/ui/router', () => ({
+    useNavigate: () => mocks.navigate,
+}));
+
+vi.mock('@vertesia/ui/session', () => ({
+    useUserSession: () => ({
+        store: { objects: { update: mocks.update } },
+    }),
+}));
+
+describe('TextEditorPanel', () => {
+    it.each(['text/markdown', 'text/x-markdown'])(
+        'uses the full rich-text document editor for %s content',
+        async (contentType) => {
+            const object = {
+                id: 'document-1',
+                content: {
+                    type: contentType,
+                    name: 'document.md',
+                    etag: 'etag-1',
+                },
+            } as unknown as ContentObject;
+
+            render(
+                <I18nProvider lng="en">
+                    <TextEditorPanel object={object} text="# Editable document" onClose={vi.fn()} onSaved={vi.fn()} />
+                </I18nProvider>,
+            );
+
+            expect(await screen.findByRole('textbox', { name: 'Markdown document editor' })).not.toBeNull();
+            expect(screen.getByRole('heading', { name: 'Editable document' })).not.toBeNull();
+            expect(await screen.findByRole('toolbar')).not.toBeNull();
+        },
+    );
+});

package/src/features/store/objects/components/TextEditorPanel.tsx

@@ -1,10 +1,12 @@
 import type { ContentObject } from '@vertesia/common';
 import { Button, errorMessage, useTheme, useToast } from '@vertesia/ui/core';
 import { useUITranslation } from '@vertesia/ui/i18n';
+import { VertesiaMarkdownDocumentEditor } from '@vertesia/ui/rich-text';
 import { useNavigate } from '@vertesia/ui/router';
 import { useUserSession } from '@vertesia/ui/session';
 import { type IEditorApi, MonacoEditor } from '@vertesia/ui/widgets';
-import { useCallback, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { isMarkdownContentType } from './documentEditingRun.js';
 import { SaveVersionConfirmModal } from './SaveVersionConfirmModal.js';
 
 interface TextEditorPanelProps {
@@ -17,6 +19,7 @@ interface TextEditorPanelProps {
 function getMonacoLanguage(contentType?: string): string {
     switch (contentType) {
         case 'text/markdown':
+        case 'text/x-markdown':
             return 'markdown';
         case 'application/json':
             return 'json';
@@ -35,34 +38,48 @@ export function TextEditorPanel({ object, text, onClose, onSaved }: TextEditorPa
     const { theme } = useTheme();
     const navigate = useNavigate();
     const editorRef = useRef<IEditorApi | undefined>(undefined);
+    const [editorText, setEditorText] = useState(text);
     const [isDirty, setIsDirty] = useState(false);
     const [isSaving, setIsSaving] = useState(false);
     const [showConfirmation, setShowConfirmation] = useState(false);
 
     const language = getMonacoLanguage(object.content?.type);
-    console.log('Determined language for Monaco Editor:', language);
-    console.log('TextEditorPanel rendered with object:', object, text);
+    const isMarkdown = isMarkdownContentType(object.content?.type);
+
+    useEffect(() => {
+        setEditorText(text);
+        setIsDirty(false);
+    }, [text]);
 
     const handleEditorChange = useCallback(() => {
         if (!isDirty) setIsDirty(true);
     }, [isDirty]);
 
+    const handleMarkdownChange = useCallback(
+        (markdown: string) => {
+            setEditorText(markdown);
+            setIsDirty(markdown !== text);
+        },
+        [text],
+    );
+
     function handleSave() {
-        if (!editorRef.current) return;
+        if (!isMarkdown && !editorRef.current) return;
         setShowConfirmation(true);
     }
 
     async function saveText(createVersion: boolean, versionLabel?: string) {
-        if (!editorRef.current) return;
+        if (!isMarkdown && !editorRef.current) return;
 
-        const editorText = editorRef.current.getValue();
+        const content = isMarkdown ? editorText : editorRef.current?.getValue();
+        if (content === undefined) return;
         const contentType = object.content?.type || 'text/plain';
         const fileName = object.content?.name || 'content.txt';
 
         try {
             setIsSaving(true);
 
-            const blob = new Blob([editorText], { type: contentType });
+            const blob = new Blob([content], { type: contentType });
             const file = new File([blob], fileName, { type: contentType });
 
             const response = await store.objects.update(
@@ -121,19 +138,23 @@ export function TextEditorPanel({ object, text, onClose, onSaved }: TextEditorPa
                 </Button>
             </div>
             <div className="flex-1 min-h-0 border rounded-md overflow-hidden mx-2 mb-2">
-                <MonacoEditor
-                    value={text}
-                    language={language}
-                    editorRef={editorRef}
-                    onChange={handleEditorChange}
-                    theme={theme === 'dark' ? 'vs-dark' : 'vs'}
-                    options={{
-                        wordWrap: 'on',
-                        minimap: { enabled: false },
-                        lineNumbers: 'on',
-                        scrollBeyondLastLine: false,
-                    }}
-                />
+                {isMarkdown ? (
+                    <VertesiaMarkdownDocumentEditor value={editorText} onChange={handleMarkdownChange} />
+                ) : (
+                    <MonacoEditor
+                        value={text}
+                        language={language}
+                        editorRef={editorRef}
+                        onChange={handleEditorChange}
+                        theme={theme === 'dark' ? 'vs-dark' : 'vs'}
+                        options={{
+                            wordWrap: 'on',
+                            minimap: { enabled: false },
+                            lineNumbers: 'on',
+                            scrollBeyondLastLine: false,
+                        }}
+                    />
+                )}
             </div>
 
             <SaveVersionConfirmModal

package/src/features/store/objects/components/VectorSearchWidget.tsx

@@ -141,7 +141,7 @@ export function VectorSearchWidget({ onChange, isLoading, refresh, searchTypes }
             <Button
                 variant="ghost"
                 onClick={() => setShowSettings(true)}
-                alt={t('store.semanticSearchSettings')}
+                title={t('store.semanticSearchSettings')}
                 className="ms-1"
             >
                 <Settings size={18} />
@@ -194,7 +194,7 @@ export function VectorSearchWidget({ onChange, isLoading, refresh, searchTypes }
                 isLoading={isLoading}
                 onClick={fireSearch}
                 isDisabled={!isReady}
-                alt={t('store.semanticSearch')}
+                title={t('store.semanticSearch')}
             >
                 {t('store.search')}
             </Button>

package/src/features/store/objects/components/documentArtifactRefs.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest';
+import { collectRunLocalArtifactRefs, persistRunLocalArtifactRefs } from './documentArtifactRefs.js';
+
+const DOC = [
+    '![Chart 1](artifact:documents/abc-123/out/01_chart.png)',
+    '![Chart 2](artifact:out/02_chart.png)',
+    '![Chart 2 again](artifact:out/02_chart.png)',
+    '![Legacy](artifact:agents/run-9/out/03_chart.png)',
+    '[data file](artifact:files/data.csv)',
+    '![external](https://example.com/x.png)',
+].join('\n');
+
+describe('collectRunLocalArtifactRefs', () => {
+    it('collects only run-local refs, deduplicated', () => {
+        expect(collectRunLocalArtifactRefs(DOC)).toEqual(['out/02_chart.png', 'files/data.csv']);
+    });
+
+    it('ignores documents/ and agents/ refs and non-artifact urls', () => {
+        expect(collectRunLocalArtifactRefs('![a](artifact:documents/x/y.png) ![b](https://e.com/i.png)')).toEqual([]);
+    });
+});
+
+describe('persistRunLocalArtifactRefs', () => {
+    it('copies each run-local ref once and rewrites all occurrences', async () => {
+        const copyFile = vi.fn().mockResolvedValue('ok');
+        const result = await persistRunLocalArtifactRefs({ copyFile }, DOC, 'run-1', 'batch-1');
+
+        expect(copyFile).toHaveBeenCalledTimes(2);
+        expect(copyFile).toHaveBeenCalledWith('agents/run-1/out/02_chart.png', 'documents/batch-1/out/02_chart.png');
+        expect(copyFile).toHaveBeenCalledWith('agents/run-1/files/data.csv', 'documents/batch-1/files/data.csv');
+
+        expect(result.content).toContain('![Chart 2](artifact:documents/batch-1/out/02_chart.png)');
+        expect(result.content).toContain('![Chart 2 again](artifact:documents/batch-1/out/02_chart.png)');
+        expect(result.content).toContain('[data file](artifact:documents/batch-1/files/data.csv)');
+        // Durable and external refs stay untouched
+        expect(result.content).toContain('artifact:documents/abc-123/out/01_chart.png');
+        expect(result.content).toContain('artifact:agents/run-9/out/03_chart.png');
+        expect(result.content).toContain('https://example.com/x.png');
+        expect(result.persisted).toHaveLength(2);
+        expect(result.failed).toHaveLength(0);
+    });
+
+    it('pins failed copies to the explicit run-scoped path', async () => {
+        const copyFile = vi.fn().mockRejectedValue(new Error('not found'));
+        const result = await persistRunLocalArtifactRefs(
+            { copyFile },
+            '![Chart 2](artifact:out/02_chart.png)',
+            'run-1',
+            'batch-1',
+        );
+
+        expect(result.content).toBe('![Chart 2](artifact:agents/run-1/out/02_chart.png)');
+        expect(result.failed).toEqual(['out/02_chart.png']);
+        expect(result.persisted).toHaveLength(0);
+    });
+
+    it('returns content unchanged and skips IO when there is nothing to persist', async () => {
+        const copyFile = vi.fn();
+        const content = '![a](artifact:documents/x/y.png)';
+        const result = await persistRunLocalArtifactRefs({ copyFile }, content, 'run-1', 'batch-1');
+
+        expect(copyFile).not.toHaveBeenCalled();
+        expect(result.content).toBe(content);
+    });
+});

package/src/features/store/objects/components/documentArtifactRefs.ts

@@ -0,0 +1,72 @@
+export interface DocumentArtifactCopyApi {
+    copyFile(source: string, dest: string): Promise<unknown>;
+}
+
+// Run-local artifact links — excludes paths already pointing at durable storage
+// (agents/ run prefixes, documents/ repository copies). Mirrors the regex used by
+// the create_document tool so both publication paths persist the same links.
+const RUN_LOCAL_ARTIFACT_REF_REGEX = /artifact:(?!agents\/)(?!documents\/)([^\s)\]"]+)/g;
+
+export function collectRunLocalArtifactRefs(content: string): string[] {
+    const refs = new Set<string>();
+    for (const match of content.matchAll(RUN_LOCAL_ARTIFACT_REF_REGEX)) {
+        refs.add(match[1].replace(/^\/+/, ''));
+    }
+    return [...refs];
+}
+
+export interface PersistRunLocalArtifactRefsResult {
+    content: string;
+    /** Links rewritten to a durable documents/ copy. */
+    persisted: Array<{ from: string; to: string }>;
+    /** Links whose copy failed; rewritten to the run-scoped agents/ path instead. */
+    failed: string[];
+}
+
+/**
+ * Copy run-local `artifact:` references into durable `documents/{batchId}/` storage
+ * and rewrite the links — the Save-to-document counterpart of the persistence pass
+ * `create_document` applies when a document is first created from agent content.
+ *
+ * Run artifact storage is scoped to the agent run and does not outlive it, so a
+ * published document must never depend on it. When a copy fails the link is pinned
+ * to the explicit run-scoped `agents/` path rather than left run-relative, so it
+ * can never silently resolve against a different run's artifact space.
+ */
+export async function persistRunLocalArtifactRefs(
+    files: DocumentArtifactCopyApi,
+    content: string,
+    agentRunId: string,
+    batchId: string,
+): Promise<PersistRunLocalArtifactRefsResult> {
+    const refs = collectRunLocalArtifactRefs(content);
+    if (refs.length === 0) {
+        return { content, persisted: [], failed: [] };
+    }
+
+    const rewrites = new Map<string, string>();
+    const persisted: Array<{ from: string; to: string }> = [];
+    const failed: string[] = [];
+    for (const relPath of refs) {
+        const destPath = `documents/${batchId}/${relPath}`;
+        try {
+            await files.copyFile(`agents/${agentRunId}/${relPath}`, destPath);
+            rewrites.set(relPath, destPath);
+            persisted.push({ from: relPath, to: destPath });
+        } catch (error: unknown) {
+            console.warn('Failed to persist a referenced artifact; keeping a run-scoped link', {
+                artifact_path: relPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            rewrites.set(relPath, `agents/${agentRunId}/${relPath}`);
+            failed.push(relPath);
+        }
+    }
+
+    const rewritten = content.replace(RUN_LOCAL_ARTIFACT_REF_REGEX, (match, relPath: string) => {
+        const destPath = rewrites.get(relPath.replace(/^\/+/, ''));
+        return destPath ? `artifact:${destPath}` : match;
+    });
+
+    return { content: rewritten, persisted, failed };
+}

package/src/features/store/objects/components/documentEditingAgentConfig.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import {
+    DOCUMENT_EDITING_EXCLUDED_TOOLS,
+    DOCUMENT_EDITING_INITIAL_SKILLS,
+    DOCUMENT_EDITING_TOOLS,
+} from './documentEditingAgentConfig.js';
+
+describe('document editing agent configuration', () => {
+    it('starts with artifact and code execution guidance and permits shell execution', () => {
+        expect(DOCUMENT_EDITING_INITIAL_SKILLS).toEqual(['artifact_operations', 'code_execution']);
+        expect(DOCUMENT_EDITING_TOOLS).toContain('execute_shell');
+        expect(DOCUMENT_EDITING_EXCLUDED_TOOLS).not.toContain('execute_shell');
+    });
+
+    it('offers relevant skills without exposing canonical document writes', () => {
+        expect(DOCUMENT_EDITING_TOOLS).toEqual(
+            expect.arrayContaining([
+                'learn_content_authoring',
+                'learn_document_management',
+                'learn_document_search',
+                'learn_image_analysis',
+            ]),
+        );
+        expect(DOCUMENT_EDITING_EXCLUDED_TOOLS).toEqual(
+            expect.arrayContaining(['create_document', 'update_document', 'merge_documents', 'batch_execute']),
+        );
+    });
+});

package/src/features/store/objects/components/documentEditingAgentConfig.ts

@@ -0,0 +1,41 @@
+export const DOCUMENT_EDITING_TOOLS = [
+    'ask_user',
+    'think',
+    'plan',
+    'update_plan',
+    'end_conversation',
+    'learn_artifact_operations',
+    'learn_code_execution',
+    'learn_content_authoring',
+    'learn_document_management',
+    'learn_document_search',
+    'learn_image_analysis',
+    // Available immediately as well as through the code_execution skill so an
+    // editing agent can regenerate charts and other derived assets.
+    'execute_shell',
+    // Read access to canonical revisions: reconcile-after-conflict and change
+    // summaries fetch other revisions into reference artifacts for comparison.
+    'fetch_document',
+];
+
+// Artifact operations and code execution are core editing capabilities, so their
+// guidance and tools are active before the first model turn. Other skills remain
+// available through their learn_* tools when the task calls for them.
+export const DOCUMENT_EDITING_INITIAL_SKILLS = ['artifact_operations', 'code_execution'];
+
+// Editing sessions mutate only the working-copy artifact; the canonical document is
+// published exclusively through Save to document. These tools stay unavailable even
+// if a skill or tool refresh would otherwise unlock them.
+export const DOCUMENT_EDITING_EXCLUDED_TOOLS = [
+    'update_document',
+    'update_document_properties',
+    'create_document',
+    'set_document_type',
+    'merge_documents',
+    'import_file',
+    'create_or_update_object_type',
+    'disable_type',
+    // Keep multi-command fan-out unavailable; execute_shell is intentionally
+    // allowed as the single, observable sandbox execution path.
+    'batch_execute',
+];

package/src/features/store/objects/components/documentEditingPrompts.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { createDirectEditsAppliedPrompt } from './documentEditingPrompts.js';
+
+describe('createDirectEditsAppliedPrompt', () => {
+    it('sends a compact unified diff with file headers', () => {
+        const prompt = createDirectEditsAppliedPrompt(
+            'drafts/document.md',
+            ['@@ -2,3 +2,3 @@', ' unchanged', '-First paragraph.', '+Updated paragraph.'].join('\n'),
+        );
+
+        expect(prompt).toContain('--- a/drafts/document.md');
+        expect(prompt).toContain('+++ b/drafts/document.md');
+        expect(prompt).toContain('@@ -2,3 +2,3 @@');
+        expect(prompt).toContain('-First paragraph.');
+        expect(prompt).toContain('+Updated paragraph.');
+        expect(prompt).toContain('do not re-apply it');
+    });
+
+    it('does not discard a unified diff larger than the previous fallback limit', () => {
+        const unifiedDiff = Array.from({ length: 600 }, (_, index) => `-${'before'.repeat(2)} ${index}`).join('\n');
+        const prompt = createDirectEditsAppliedPrompt('drafts/large.md', unifiedDiff);
+
+        expect(prompt.length).toBeGreaterThan(4000);
+        expect(prompt).toContain('-beforebefore 599');
+    });
+});

package/src/features/store/objects/components/documentEditingPrompts.ts

@@ -0,0 +1,12 @@
+/** Chat notice handing the agent direct editor edits that already exist in the working copy. */
+export function createDirectEditsAppliedPrompt(draftPath: string, unifiedDiff: string): string {
+    return [
+        `Direct edits are already saved to '${draftPath}'. Use this compact unified diff as context only;`,
+        'do not re-apply it. The artifact remains the current source of truth.',
+        '```diff',
+        `--- a/${draftPath}`,
+        `+++ b/${draftPath}`,
+        unifiedDiff,
+        '```',
+    ].join('\n');
+}

package/src/features/store/objects/components/documentEditingRun.test.ts

@@ -0,0 +1,176 @@
+import type { AgentRun } from '@vertesia/common';
+import { describe, expect, it, vi } from 'vitest';
+import {
+    createDocumentEditingRunIdentity,
+    createDocumentEditingScopeKey,
+    findDocumentEditingRun,
+    getDocumentTextActionAccess,
+    isDocumentEditingContentType,
+    isDocumentEditingRun,
+    isDocumentEditingScopeOpen,
+    isMarkdownContentType,
+    setDocumentEditingScopeOpen,
+} from './documentEditingRun.js';
+
+const startedBy = 'user:user-1';
+
+function createRun(overrides: Partial<AgentRun> = {}): AgentRun {
+    return {
+        id: 'run-1',
+        run_kind: 'agent',
+        run_type: 'autonomous',
+        interaction: 'sys:GeneralAgent',
+        interactionRef: { id: 'sys:GeneralAgent' },
+        status: 'running',
+        started_by: startedBy,
+        started_at: new Date(),
+        created_at: new Date(),
+        updated_at: new Date(),
+        ...overrides,
+    } as AgentRun;
+}
+
+describe('document editing run identity', () => {
+    it('keeps the editing panel open across document component remounts', () => {
+        const scopeKey = createDocumentEditingScopeKey('project-1', 'document-root');
+
+        setDocumentEditingScopeOpen(scopeKey, true);
+        expect(isDocumentEditingScopeOpen(scopeKey)).toBe(true);
+
+        setDocumentEditingScopeOpen(scopeKey, false);
+        expect(isDocumentEditingScopeOpen(scopeKey)).toBe(false);
+    });
+
+    it('keeps collaboration access independent from direct editing access', () => {
+        expect(getDocumentTextActionAccess(false, true)).toEqual({
+            canEdit: false,
+            canCollaborate: true,
+        });
+    });
+
+    it.each(['text/markdown', 'text/x-markdown', 'text/plain', 'TEXT/MARKDOWN; charset=utf-8'])(
+        'allows AI document editing for %s',
+        (contentType) => {
+            expect(isDocumentEditingContentType(contentType)).toBe(true);
+        },
+    );
+
+    it.each(['application/octet-stream', 'application/json', undefined])(
+        'does not treat %s as AI-editable text',
+        (contentType) => {
+            expect(isDocumentEditingContentType(contentType)).toBe(false);
+        },
+    );
+
+    it('recognizes canonical and legacy Markdown MIME types', () => {
+        expect(isMarkdownContentType('text/markdown')).toBe(true);
+        expect(isMarkdownContentType('text/x-markdown')).toBe(true);
+        expect(isMarkdownContentType('text/plain')).toBe(false);
+    });
+
+    it('creates stable revision-root tags and properties', () => {
+        expect(createDocumentEditingRunIdentity('document-2', 'document-root')).toEqual({
+            tags: ['document-editing', 'document-root:document-root', 'document:document-2'],
+            properties: {
+                resource_kind: 'store_document',
+                document_id: 'document-2',
+                document_root_id: 'document-root',
+            },
+        });
+    });
+
+    it('requires the same user and matching root properties for stable runs', () => {
+        const identity = createDocumentEditingRunIdentity('document-2', 'document-root');
+        const run = createRun(identity);
+
+        expect(isDocumentEditingRun(run, 'document-3', 'document-root', startedBy)).toBe(true);
+        expect(isDocumentEditingRun(run, 'document-3', 'another-root', startedBy)).toBe(false);
+        expect(isDocumentEditingRun(run, 'document-3', 'document-root', 'user:user-2')).toBe(false);
+    });
+
+    it('reattaches a legacy document-tagged run owned by the user', () => {
+        const run = createRun({ tags: ['document-editing', 'document:document-root'] });
+
+        expect(isDocumentEditingRun(run, 'document-2', 'document-root', startedBy)).toBe(true);
+    });
+
+    it('never resumes a run the user terminated', () => {
+        const identity = createDocumentEditingRunIdentity('document-2', 'document-root');
+        const run = createRun({ ...identity, status: 'cancelled' });
+
+        expect(isDocumentEditingRun(run, 'document-2', 'document-root', startedBy)).toBe(false);
+    });
+
+    it('matches the interaction configured for the document type', () => {
+        const identity = createDocumentEditingRunIdentity('document-2', 'document-root');
+        const run = createRun({ ...identity, interaction: 'custom-editor' });
+
+        expect(isDocumentEditingRun(run, 'document-2', 'document-root', startedBy, 'custom-editor')).toBe(true);
+        expect(isDocumentEditingRun(run, 'document-2', 'document-root', startedBy)).toBe(false);
+    });
+});
+
+describe('findDocumentEditingRun', () => {
+    it('searches by root tag and verifies the retrieved run', async () => {
+        const identity = createDocumentEditingRunIdentity('document-2', 'document-root');
+        const run = createRun(identity);
+        const agents = {
+            search: vi.fn().mockResolvedValue({
+                hits: [{ id: run.id, created_at: '2026-01-01', updated_at: '2026-01-02' }],
+                total: 1,
+            }),
+            retrieve: vi.fn().mockResolvedValue(run),
+            list: vi.fn(),
+        };
+
+        await expect(findDocumentEditingRun(agents, 'document-2', 'document-root', startedBy)).resolves.toBe(run);
+        expect(agents.search).toHaveBeenCalledWith({
+            interaction: 'sys:GeneralAgent',
+            started_by: startedBy,
+            tags: ['document-root:document-root'],
+            limit: 20,
+            sort: ['updated_at:desc'],
+        });
+        expect(agents.list).not.toHaveBeenCalled();
+    });
+
+    it('falls back to recent user-owned runs when search is unavailable', async () => {
+        const run = createRun({ tags: ['document-editing', 'document:document-root'] });
+        const agents = {
+            search: vi.fn().mockRejectedValue(new Error('search unavailable')),
+            retrieve: vi.fn(),
+            list: vi.fn().mockResolvedValue({ items: [run], total_count: 1, next_cursor: null }),
+        };
+
+        await expect(findDocumentEditingRun(agents, 'document-2', 'document-root', startedBy)).resolves.toBe(run);
+        expect(agents.list).toHaveBeenCalledWith({
+            interaction: 'sys:GeneralAgent',
+            started_by: startedBy,
+            limit: 100,
+            sort: 'updated_at',
+            order: 'desc',
+        });
+    });
+
+    it('searches and validates runs using a type-specific interaction', async () => {
+        const identity = createDocumentEditingRunIdentity('document-2', 'document-root');
+        const run = createRun({ ...identity, interaction: 'custom-editor' });
+        const agents = {
+            search: vi.fn().mockResolvedValue({
+                hits: [{ id: run.id, created_at: '2026-01-01', updated_at: '2026-01-02' }],
+                total: 1,
+            }),
+            retrieve: vi.fn().mockResolvedValue(run),
+            list: vi.fn(),
+        };
+
+        await expect(
+            findDocumentEditingRun(agents, 'document-2', 'document-root', startedBy, 'custom-editor'),
+        ).resolves.toBe(run);
+        expect(agents.search).toHaveBeenCalledWith(
+            expect.objectContaining({
+                interaction: 'custom-editor',
+            }),
+        );
+    });
+});