rol-websocket-channel 1.8.6 → 1.8.8

package/dist/src/admin/methods/artifacts.js

@@ -4,11 +4,14 @@ import path from 'node:path';
 import { ensureDir, pathExists, readJsonFile } from '../lib/fs.js';
 import { ensureInside } from '../lib/paths.js';
 import { JsonRpcException, JSON_RPC_ERRORS } from '../jsonrpc.js';
+import { findSessionRecord } from './sessions.js';
 const INLINE_CONTENT_LIMIT_BYTES = 10 * 1024 * 1024;
 const MIN_ARTIFACT_SIZE_BYTES = 1;
 const ARTIFACT_MANIFEST_FILE = 'artifacts.json';
 const MARKDOWN_SCAN_STATE_FILE = 'md-scan-state.json';
+const ARTIFACT_ARCHIVE_STATE_FILE = 'artifact-archive-state.json';
 const PLUGIN_WORKSPACE_STATE_DIR = path.join('.openclaw', 'rol-websocket-channel');
+const SESSION_ARTIFACTS_ROOT_RELATIVE = 'artifacts/sessions';
 const IGNORE_EXTENSIONS = new Set(['.tmp', '.part', '.crdownload']);
 const IGNORE_FILE_NAMES = new Set(['.ds_store', 'thumbs.db', ARTIFACT_MANIFEST_FILE]);
 const IGNORE_MARKDOWN_FILE_NAMES = new Set([
@@ -83,27 +86,46 @@ const MIME_BY_EXTENSION = {
 export const listArtifacts = async (params, context) => {
     const objectParams = expectOptionalObject(params);
     const refresh = objectParams.refresh !== false;
+    const normalizedFilters = normalizeArtifactFilters(objectParams);
+    const filters = {
+        ...normalizedFilters,
+        sessionId: await resolveCanonicalArtifactSessionId(context, normalizedFilters.sessionId)
+    };
+    const groupBy = normalizeArtifactGroupBy(objectParams.groupBy);
     const manifest = refresh
-        ? await refreshArtifactManifest(context)
+        ? await refreshArtifactManifest(context, { sessionId: filters.sessionId })
         : await readOrRefreshArtifactManifest(context);
-    return {
-        scope: 'workspace',
-        count: manifest.items.length,
+    const items = manifest.items.filter((item) => matchesArtifactFilters(item, filters));
+    const response = {
+        scope: filters.sessionId ? 'session' : 'workspace',
+        sessionId: filters.sessionId ?? null,
+        query: filters.query ?? null,
+        count: items.length,
         manifestPath: manifest.manifestPath,
         workspaceRoot: manifest.workspacePaths.workspaceRoot,
-        items: manifest.items.map(artifactToJsonValue)
+        items: items.map(artifactToJsonValue)
     };
+    if (groupBy) {
+        response.groupBy = groupBy;
+        response.groups = buildArtifactGroups(items, groupBy);
+    }
+    return response;
 };
 export const refreshArtifacts = async (params, context) => {
     const objectParams = expectOptionalObject(params);
-    const manifest = await refreshArtifactManifest(context);
+    const sessionId = await resolveCanonicalArtifactSessionId(context, optionalTrimmedString(objectParams.sessionId));
+    const manifest = await refreshArtifactManifest(context, { sessionId });
+    const items = sessionId
+        ? manifest.items.filter((item) => item.sessionId === sessionId)
+        : manifest.items;
     return {
         ok: true,
-        scope: 'workspace',
-        count: manifest.items.length,
+        scope: sessionId ? 'session' : 'workspace',
+        sessionId: sessionId ?? null,
+        count: items.length,
         manifestPath: manifest.manifestPath,
         workspaceRoot: manifest.workspacePaths.workspaceRoot,
-        items: manifest.items.map(artifactToJsonValue)
+        items: items.map(artifactToJsonValue)
     };
 };
 export const getArtifactContent = async (params, context) => {
@@ -129,10 +151,12 @@ export const getArtifactContent = async (params, context) => {
 export const ensureArtifactUploaded = async (params, context) => {
     const objectParams = expectObject(params);
     const artifact = await resolveArtifact(objectParams, context);
+    const scope = artifact.sessionId ? 'session' : 'workspace';
     if (artifact.storageStatus === 'uploaded' && artifact.fileUrl) {
         return {
             ok: true,
-            scope: 'workspace',
+            scope,
+            sessionId: artifact.sessionId ?? null,
             uploaded: false,
             artifactId: artifact.id,
             objectKey: artifact.objectKey ?? null,
@@ -161,7 +185,8 @@ export const ensureArtifactUploaded = async (params, context) => {
     });
     return {
         ok: true,
-        scope: 'workspace',
+        scope,
+        sessionId: artifact.sessionId ?? null,
         uploaded: true,
         artifactId: artifact.id,
         objectKey,
@@ -178,6 +203,9 @@ export const publishArtifact = async (params, context) => {
     const uploadParams = {
         artifactId: artifact.id
     };
+    if (artifact.sessionId) {
+        uploadParams.sessionId = artifact.sessionId;
+    }
     if (objectParams.presignedPostBody !== undefined) {
         uploadParams.presignedPostBody = objectParams.presignedPostBody;
     }
@@ -192,21 +220,32 @@ export const publishArtifact = async (params, context) => {
 export const findLatestArtifacts = async (params, context) => {
     const objectParams = expectOptionalObject(params);
     const refresh = objectParams.refresh !== false;
+    const normalizedFilters = normalizeArtifactFindFilters(objectParams);
+    const filters = {
+        ...normalizedFilters,
+        sessionId: await resolveCanonicalArtifactSessionId(context, normalizedFilters.sessionId)
+    };
     const manifest = refresh
-        ? await refreshArtifactManifest(context)
+        ? await refreshArtifactManifest(context, { sessionId: filters.sessionId })
         : await readOrRefreshArtifactManifest(context);
-    const filters = normalizeArtifactFindFilters(objectParams);
-    const items = manifest.items
+    const groupBy = normalizeArtifactGroupBy(objectParams.groupBy);
+    const matchedItems = manifest.items
         .filter((item) => matchesArtifactFindFilters(item, filters))
         .sort(compareArtifactsByRecency)
-        .slice(0, filters.limit)
-        .map(artifactToJsonValue);
-    return {
+        .slice(0, filters.limit);
+    const response = {
         ok: true,
-        scope: 'workspace',
-        count: items.length,
-        items
+        scope: filters.sessionId ? 'session' : 'workspace',
+        sessionId: filters.sessionId ?? null,
+        query: filters.query ?? null,
+        count: matchedItems.length,
+        items: matchedItems.map(artifactToJsonValue)
     };
+    if (groupBy) {
+        response.groupBy = groupBy;
+        response.groups = buildArtifactGroups(matchedItems, groupBy);
+    }
+    return response;
 };
 export const getArtifactPresignedPost = async (params, context) => {
     const objectParams = expectObject(params);
@@ -248,11 +287,15 @@ export const markArtifactUploaded = async (params, context) => {
         throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'At least one of objectKey or fileUrl is required');
     }
     const manifest = await readOrRefreshArtifactManifest(context);
-    const artifact = findArtifact(manifest.items, objectParams);
+    const sessionId = await resolveCanonicalArtifactSessionId(context, optionalTrimmedString(objectParams.sessionId));
+    const artifact = findArtifact(manifest.items, objectParams, {
+        sessionId
+    });
     if (!artifact) {
         throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Artifact not found', {
             artifactId: objectParams.artifactId,
-            relativePath: objectParams.relativePath
+            relativePath: objectParams.relativePath,
+            sessionId
         });
     }
     const updated = await persistUploadedArtifact(manifest.manifestPath, manifest.items, artifact.id, {
@@ -262,7 +305,8 @@ export const markArtifactUploaded = async (params, context) => {
     });
     return {
         ok: true,
-        scope: 'workspace',
+        scope: updated.sessionId ? 'session' : 'workspace',
+        sessionId: updated.sessionId ?? null,
         artifactId: artifact.id,
         item: artifactToJsonValue(updated)
     };
@@ -285,7 +329,8 @@ export function shouldIgnoreArtifactFile(fileName) {
     const ext = path.extname(normalized);
     return IGNORE_EXTENSIONS.has(ext);
 }
-async function refreshArtifactManifest(context) {
+async function refreshArtifactManifest(context, options) {
+    const taggedSessionId = optionalTrimmedString(options?.sessionId);
     const workspacePaths = await ensureWorkspacePaths(context.openclawRoot);
     const { workspaceRoot, manifestPath } = workspacePaths;
     const existing = await readExistingManifest(manifestPath);
@@ -293,28 +338,69 @@ async function refreshArtifactManifest(context) {
     const loadedMarkdownScanState = await readMarkdownScanState(workspacePaths.markdownScanStatePath);
     const hadMarkdownScanState = loadedMarkdownScanState !== null;
     const markdownScanState = loadedMarkdownScanState ?? createMarkdownScanState();
-    const files = await collectArtifactFiles(workspaceRoot);
+    const archiveState = await readArtifactArchiveState(workspacePaths.artifactArchiveStatePath);
+    const files = (await collectArtifactFiles(workspaceRoot))
+        .sort((left, right) => compareDiscoveredArtifactPaths(workspaceRoot, left, right));
+    const discoveredRelativePaths = new Set(files.map((filePath) => path.relative(workspaceRoot, filePath).replace(/\\/g, '/')));
+    const emittedRelativePaths = new Set();
     const items = [];
-    for (const fullPath of files) {
-        const stat = await fs.stat(fullPath);
+    for (const discoveredFullPath of files) {
+        let fullPath = discoveredFullPath;
+        let stat = await fs.stat(fullPath);
         if (!stat.isFile() || stat.size < MIN_ARTIFACT_SIZE_BYTES) {
             continue;
         }
-        const relativePath = path.relative(workspaceRoot, fullPath).replace(/\\/g, '/');
-        const existingItem = existingByPath.get(relativePath);
+        let relativePath = path.relative(workspaceRoot, fullPath).replace(/\\/g, '/');
+        let existingItem = existingByPath.get(relativePath);
         const fileName = path.basename(fullPath);
+        const pathSessionId = extractSessionIdFromArtifactRelativePath(relativePath);
         const isMarkdown = isMarkdownArtifactFile(fileName);
         if (isMarkdown) {
-            if (!shouldIncludeMarkdownArtifactFile(relativePath, fileName, stat, markdownScanState, hadMarkdownScanState)) {
+            if (!shouldIncludeMarkdownArtifactFile(relativePath, fileName, stat, markdownScanState, hadMarkdownScanState, Boolean(taggedSessionId || pathSessionId))) {
                 continue;
             }
         }
         else if (!shouldIncludeArtifactFile(fileName)) {
             continue;
         }
+        const archiveEntry = archiveState.files[relativePath];
+        if (!pathSessionId) {
+            if (archiveEntry && await artifactArchiveEntryIsCurrent(workspaceRoot, archiveEntry, stat)) {
+                if (!taggedSessionId) {
+                    continue;
+                }
+                const archivedSessionId = await resolveArchiveStateSessionId(context, archiveEntry.sessionId);
+                if (archivedSessionId && (archivedSessionId !== taggedSessionId || archiveEntry.sessionId === taggedSessionId)) {
+                    continue;
+                }
+            }
+            if (taggedSessionId) {
+                const archivedRelativePath = await copyArtifactFileToSessionDirectory(workspaceRoot, taggedSessionId, relativePath, fullPath, stat, existingByPath, archiveEntry);
+                archiveState.files[relativePath] = {
+                    sessionId: taggedSessionId,
+                    targetRelativePath: archivedRelativePath,
+                    sizeBytes: stat.size,
+                    mtimeMs: stat.mtimeMs,
+                    archivedAt: new Date().toISOString()
+                };
+                if (discoveredRelativePaths.has(archivedRelativePath)) {
+                    continue;
+                }
+                fullPath = ensureInside(workspaceRoot, path.join(workspaceRoot, archivedRelativePath));
+                relativePath = archivedRelativePath;
+                existingItem = existingByPath.get(relativePath);
+                stat = await fs.stat(fullPath);
+            }
+        }
+        if (emittedRelativePaths.has(relativePath)) {
+            continue;
+        }
         const ext = normalizeExtension(fileName);
         const createdAt = normalizeTimestamp(stat.birthtime, stat.mtime);
-        const updatedAt = stat.mtime.toISOString();
+        let updatedAt = stat.mtime.toISOString();
+        let currentStat = stat;
+        const resolvedSessionId = resolveArtifactSessionId(relativePath, existingItem, taggedSessionId);
+        emittedRelativePaths.add(relativePath);
         items.push({
             id: existingItem?.id ?? buildArtifactId(relativePath),
             fileName,
@@ -323,9 +409,10 @@ async function refreshArtifactManifest(context) {
             category: classifyArtifactCategory(fileName),
             mimeType: MIME_BY_EXTENSION[ext ?? ''] ?? 'application/octet-stream',
             ext,
-            sizeBytes: stat.size,
+            sizeBytes: currentStat.size,
             storageStatus: existingItem?.storageStatus ?? 'local_only',
             source: existingItem?.source ?? 'generated',
+            sessionId: resolvedSessionId,
             previewable: isPreviewableCategory(classifyArtifactCategory(fileName)),
             createdAt: existingItem?.createdAt ?? createdAt,
             updatedAt,
@@ -338,6 +425,7 @@ async function refreshArtifactManifest(context) {
     items.sort((a, b) => a.fileName.localeCompare(b.fileName));
     markdownScanState.lastScanAt = new Date().toISOString();
     await writeMarkdownScanState(workspacePaths.markdownScanStatePath, markdownScanState);
+    await writeArtifactArchiveState(workspacePaths.artifactArchiveStatePath, archiveState);
     await writeArtifactManifest(manifestPath, items);
     return { manifestPath, items, workspacePaths };
 }
@@ -395,6 +483,30 @@ async function writeMarkdownScanState(statePath, state) {
     await ensureDir(path.dirname(statePath));
     await fs.writeFile(statePath, JSON.stringify(state, null, 2), 'utf8');
 }
+async function readArtifactArchiveState(statePath) {
+    if (!(await pathExists(statePath))) {
+        return createArtifactArchiveState();
+    }
+    const parsed = await readJsonFile(statePath);
+    if (!isObject(parsed) || !isObject(parsed.files)) {
+        return createArtifactArchiveState();
+    }
+    const files = {};
+    for (const [relativePath, value] of Object.entries(parsed.files)) {
+        const normalizedRelativePath = normalizeRelativePath(relativePath);
+        if (normalizedRelativePath && isArtifactArchiveStateFile(value)) {
+            files[normalizedRelativePath] = value;
+        }
+    }
+    return {
+        version: 1,
+        files
+    };
+}
+async function writeArtifactArchiveState(statePath, state) {
+    await ensureDir(path.dirname(statePath));
+    await fs.writeFile(statePath, JSON.stringify(state, null, 2), 'utf8');
+}
 async function persistUploadedArtifact(manifestPath, items, artifactId, updates) {
     const now = new Date().toISOString();
     let updatedArtifact = null;
@@ -421,19 +533,20 @@ async function persistUploadedArtifact(manifestPath, items, artifactId, updates)
     }
     return updatedArtifact;
 }
-async function collectArtifactFiles(rootDir) {
+async function collectArtifactFiles(rootDir, baseDir = rootDir) {
     const files = [];
     const entries = await fs.readdir(rootDir, { withFileTypes: true });
     for (const entry of entries) {
-        if (entry.isDirectory() && shouldIgnoreArtifactDirectory(entry.name)) {
+        const fullPath = path.join(rootDir, entry.name);
+        const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+        if (entry.isDirectory() && shouldIgnoreArtifactDirectory(entry.name, relativePath)) {
             continue;
         }
         if (entry.isFile() && shouldIgnoreArtifactFile(entry.name)) {
             continue;
         }
-        const fullPath = path.join(rootDir, entry.name);
         if (entry.isDirectory()) {
-            files.push(...await collectArtifactFiles(fullPath));
+            files.push(...await collectArtifactFiles(fullPath, baseDir));
             continue;
         }
         if (entry.isFile()) {
@@ -442,15 +555,47 @@ async function collectArtifactFiles(rootDir) {
     }
     return files;
 }
+function compareDiscoveredArtifactPaths(workspaceRoot, left, right) {
+    const leftRelative = path.relative(workspaceRoot, left).replace(/\\/g, '/');
+    const rightRelative = path.relative(workspaceRoot, right).replace(/\\/g, '/');
+    const leftIsSessionArtifact = Boolean(extractSessionIdFromArtifactRelativePath(leftRelative));
+    const rightIsSessionArtifact = Boolean(extractSessionIdFromArtifactRelativePath(rightRelative));
+    if (leftIsSessionArtifact !== rightIsSessionArtifact) {
+        return leftIsSessionArtifact ? 1 : -1;
+    }
+    return leftRelative.localeCompare(rightRelative);
+}
+async function artifactArchiveEntryIsCurrent(workspaceRoot, entry, stat) {
+    if (entry.sizeBytes !== stat.size || entry.mtimeMs !== stat.mtimeMs) {
+        return false;
+    }
+    const targetFullPath = ensureInside(workspaceRoot, path.join(workspaceRoot, entry.targetRelativePath));
+    return await pathExists(targetFullPath);
+}
+async function copyArtifactFileToSessionDirectory(workspaceRoot, sessionId, sourceRelativePath, sourceFullPath, sourceStat, existingByPath, archiveEntry) {
+    const targetRelativePath = archiveEntry?.sessionId === sessionId
+        ? archiveEntry.targetRelativePath
+        : await resolveAvailableSessionArtifactRelativePath(workspaceRoot, sessionId, sourceRelativePath, existingByPath);
+    const targetFullPath = ensureInside(workspaceRoot, path.join(workspaceRoot, targetRelativePath));
+    await ensureDir(path.dirname(targetFullPath));
+    await fs.copyFile(sourceFullPath, targetFullPath);
+    await fs.utimes(targetFullPath, new Date(), new Date(sourceStat.mtimeMs));
+    return targetRelativePath;
+}
 async function resolveArtifact(params, context, options) {
+    const sessionId = await resolveCanonicalArtifactSessionId(context, optionalTrimmedString(params.sessionId));
+    const preparedSelector = options?.refreshManifest && sessionId
+        ? await prepareSessionArtifactSelector(params, context, sessionId)
+        : params;
     const manifest = options?.refreshManifest
-        ? await refreshArtifactManifest(context)
+        ? await refreshArtifactManifest(context, { sessionId })
         : await readOrRefreshArtifactManifest(context);
-    const artifact = findArtifact(manifest.items, params);
+    const artifact = findArtifact(manifest.items, preparedSelector, { sessionId });
     if (!artifact) {
         throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Artifact not found', {
             artifactId: params.artifactId,
-            relativePath: params.relativePath
+            relativePath: params.relativePath,
+            sessionId
         });
     }
     const checkedPath = ensureInside(manifest.workspacePaths.workspaceRoot, artifact.localPath);
@@ -464,19 +609,99 @@ async function resolveArtifact(params, context, options) {
         localPath: checkedPath
     };
 }
-function findArtifact(items, selector) {
+async function prepareSessionArtifactSelector(params, context, sessionId) {
+    const relativePath = normalizeRelativePath(optionalTrimmedString(params.relativePath));
+    if (relativePath) {
+        const archivedRelativePath = await archiveArtifactFileToSessionDirectory(context, sessionId, relativePath);
+        return {
+            ...params,
+            relativePath: archivedRelativePath ?? relativePath,
+            sessionId
+        };
+    }
+    const artifactId = optionalTrimmedString(params.artifactId);
+    if (!artifactId) {
+        return { ...params, sessionId };
+    }
+    const manifest = await readOrRefreshArtifactManifest(context);
+    const artifact = findArtifact(manifest.items, { artifactId });
+    if (!artifact || artifact.sessionId === sessionId) {
+        return { ...params, sessionId };
+    }
+    if (artifact.sessionId) {
+        return { ...params, sessionId };
+    }
+    const archivedRelativePath = await archiveArtifactFileToSessionDirectory(context, sessionId, artifact.relativePath);
+    return {
+        relativePath: archivedRelativePath ?? artifact.relativePath,
+        sessionId
+    };
+}
+async function archiveArtifactFileToSessionDirectory(context, sessionId, sourceRelativePath) {
+    const normalizedSourcePath = normalizeRelativePath(sourceRelativePath);
+    if (!normalizedSourcePath || extractSessionIdFromArtifactRelativePath(normalizedSourcePath)) {
+        return normalizedSourcePath;
+    }
+    const workspacePaths = await ensureWorkspacePaths(context.openclawRoot);
+    const sourceFullPath = ensureInside(workspacePaths.workspaceRoot, path.join(workspacePaths.workspaceRoot, normalizedSourcePath));
+    if (!(await pathExists(sourceFullPath))) {
+        return null;
+    }
+    const sourceStat = await fs.stat(sourceFullPath);
+    if (!sourceStat.isFile()) {
+        return null;
+    }
+    const existing = await readExistingManifest(workspacePaths.manifestPath);
+    const existingByPath = new Map(existing.map((item) => [item.relativePath, item]));
+    const archiveState = await readArtifactArchiveState(workspacePaths.artifactArchiveStatePath);
+    const archiveEntry = archiveState.files[normalizedSourcePath];
+    if (archiveEntry &&
+        archiveEntry.sessionId === sessionId &&
+        await artifactArchiveEntryIsCurrent(workspacePaths.workspaceRoot, archiveEntry, sourceStat)) {
+        return archiveEntry.targetRelativePath;
+    }
+    const targetRelativePath = await copyArtifactFileToSessionDirectory(workspacePaths.workspaceRoot, sessionId, normalizedSourcePath, sourceFullPath, sourceStat, existingByPath, archiveEntry);
+    archiveState.files[normalizedSourcePath] = {
+        sessionId,
+        targetRelativePath,
+        sizeBytes: sourceStat.size,
+        mtimeMs: sourceStat.mtimeMs,
+        archivedAt: new Date().toISOString()
+    };
+    await writeArtifactArchiveState(workspacePaths.artifactArchiveStatePath, archiveState);
+    return targetRelativePath;
+}
+function findArtifact(items, selector, options) {
     const artifactId = optionalTrimmedString(selector.artifactId);
     const relativePath = normalizeRelativePath(optionalTrimmedString(selector.relativePath));
+    const sessionId = optionalTrimmedString(options?.sessionId);
     if (!artifactId && !relativePath) {
         throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Either artifactId or relativePath is required');
     }
     return items.find((item) => {
+        if (sessionId && item.sessionId !== sessionId) {
+            return false;
+        }
         if (artifactId && item.id === artifactId) {
             return true;
         }
-        return Boolean(relativePath && item.relativePath === relativePath);
+        return Boolean(relativePath && artifactRelativePathMatches(item, relativePath, sessionId));
     }) ?? null;
 }
+function artifactRelativePathMatches(item, relativePath, sessionId) {
+    if (item.relativePath === relativePath) {
+        return true;
+    }
+    if (!sessionId) {
+        return false;
+    }
+    const sessionRelativePath = buildSessionArtifactRelativePath(sessionId, relativePath);
+    return item.relativePath === sessionRelativePath;
+}
+function buildSessionArtifactRelativePath(sessionId, relativePath) {
+    const normalizedRelativePath = normalizeRelativePath(relativePath) ?? path.posix.basename(relativePath);
+    return `${SESSION_ARTIFACTS_ROOT_RELATIVE}/${safeSessionDirectoryName(sessionId)}/${normalizedRelativePath}`;
+}
 function resolveWorkspaceRoot(openclawRoot) {
     const workspaceRoot = path.join(openclawRoot, 'workspace');
     return ensureInside(openclawRoot, workspaceRoot);
@@ -485,11 +710,13 @@ async function ensureWorkspacePaths(openclawRoot) {
     const workspaceRoot = resolveWorkspaceRoot(openclawRoot);
     const manifestPath = ensureInside(workspaceRoot, path.join(workspaceRoot, ARTIFACT_MANIFEST_FILE));
     const markdownScanStatePath = ensureInside(workspaceRoot, path.join(workspaceRoot, PLUGIN_WORKSPACE_STATE_DIR, MARKDOWN_SCAN_STATE_FILE));
+    const artifactArchiveStatePath = ensureInside(workspaceRoot, path.join(workspaceRoot, PLUGIN_WORKSPACE_STATE_DIR, ARTIFACT_ARCHIVE_STATE_FILE));
     await ensureDir(workspaceRoot);
     return {
         workspaceRoot,
         manifestPath,
-        markdownScanStatePath
+        markdownScanStatePath,
+        artifactArchiveStatePath
     };
 }
 function createMarkdownScanState() {
@@ -500,9 +727,94 @@ function createMarkdownScanState() {
         files: {}
     };
 }
+function createArtifactArchiveState() {
+    return {
+        version: 1,
+        files: {}
+    };
+}
 function buildArtifactId(relativePath) {
     return `art_${createHash('sha1').update(relativePath).digest('hex').slice(0, 12)}`;
 }
+async function resolveCanonicalArtifactSessionId(context, sessionIdOrKey) {
+    if (!sessionIdOrKey) {
+        return null;
+    }
+    const session = await findSessionRecord(context, sessionIdOrKey).catch(() => null);
+    if (session?.sessionId) {
+        return session.sessionId;
+    }
+    if (looksLikeOpenClawSessionKey(sessionIdOrKey)) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, `Session key not found: ${sessionIdOrKey}`, { sessionKey: sessionIdOrKey });
+    }
+    return sessionIdOrKey;
+}
+async function resolveArchiveStateSessionId(context, sessionIdOrKey) {
+    try {
+        return await resolveCanonicalArtifactSessionId(context, sessionIdOrKey);
+    }
+    catch (error) {
+        if (looksLikeOpenClawSessionKey(sessionIdOrKey)) {
+            return null;
+        }
+        throw error;
+    }
+}
+function looksLikeOpenClawSessionKey(value) {
+    return value.trim().toLowerCase().startsWith('agent:');
+}
+async function resolveAvailableSessionArtifactRelativePath(workspaceRoot, sessionId, sourceRelativePath, existingByPath) {
+    const normalizedSourcePath = normalizeRelativePath(sourceRelativePath) ?? path.basename(sourceRelativePath);
+    const sessionRoot = `${SESSION_ARTIFACTS_ROOT_RELATIVE}/${safeSessionDirectoryName(sessionId)}`;
+    const initialTarget = `${sessionRoot}/${normalizedSourcePath}`;
+    const parsed = path.posix.parse(initialTarget);
+    let candidate = initialTarget;
+    let suffix = 1;
+    while (existingByPath.has(candidate) ||
+        await pathExists(ensureInside(workspaceRoot, path.join(workspaceRoot, candidate)))) {
+        candidate = path.posix.join(parsed.dir, `${parsed.name}-${suffix}${parsed.ext}`);
+        suffix += 1;
+    }
+    return candidate;
+}
+function safeSessionDirectoryName(sessionId) {
+    const trimmed = sessionId.trim();
+    const sanitized = trimmed
+        .replace(/[<>:"/\\|?*\x00-\x1F]/g, '_')
+        .replace(/^\.+$/, '_')
+        .replace(/[. ]+$/g, '')
+        .slice(0, 120);
+    if (sanitized) {
+        return sanitized;
+    }
+    return createHash('sha1').update(trimmed).digest('hex').slice(0, 12);
+}
+function extractSessionIdFromArtifactRelativePath(relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    if (!normalized) {
+        return null;
+    }
+    const prefix = `${SESSION_ARTIFACTS_ROOT_RELATIVE}/`;
+    if (!normalized.startsWith(prefix)) {
+        return null;
+    }
+    const rest = normalized.slice(prefix.length);
+    const sessionId = rest.split('/')[0]?.trim();
+    return sessionId || null;
+}
+function resolveArtifactSessionId(relativePath, existingItem, taggedSessionId) {
+    if (existingItem) {
+        return existingItem.sessionId ?? null;
+    }
+    const pathSessionId = extractSessionIdFromArtifactRelativePath(relativePath);
+    if (!pathSessionId) {
+        return taggedSessionId ?? null;
+    }
+    if (taggedSessionId && pathSessionId === safeSessionDirectoryName(taggedSessionId)) {
+        return taggedSessionId;
+    }
+    return pathSessionId;
+}
 function normalizeExtension(fileName) {
     const ext = path.extname(fileName).toLowerCase();
     return ext || null;
@@ -531,7 +843,12 @@ function normalizeMaxInlineBytes(value) {
 function isPreviewableCategory(category) {
     return category === 'image' || category === 'video' || category === 'document';
 }
-function shouldIgnoreArtifactDirectory(dirName) {
+function shouldIgnoreArtifactDirectory(dirName, relativePath) {
+    const normalizedRelativePath = relativePath?.replace(/\\/g, '/').toLowerCase();
+    if (normalizedRelativePath === SESSION_ARTIFACTS_ROOT_RELATIVE ||
+        normalizedRelativePath?.startsWith(`${SESSION_ARTIFACTS_ROOT_RELATIVE}/`)) {
+        return false;
+    }
     const normalized = dirName.trim().toLowerCase();
     return !normalized || normalized.startsWith('.') || IGNORE_DIRECTORY_NAMES.has(normalized);
 }
@@ -541,7 +858,7 @@ function shouldIncludeArtifactFile(fileName) {
     }
     return classifyArtifactCategory(fileName) !== 'other';
 }
-function shouldIncludeMarkdownArtifactFile(relativePath, fileName, stat, state, hadState) {
+function shouldIncludeMarkdownArtifactFile(relativePath, fileName, stat, state, hadState, includeNewFile) {
     if (shouldIgnoreArtifactFile(fileName)) {
         return false;
     }
@@ -558,9 +875,9 @@ function shouldIncludeMarkdownArtifactFile(relativePath, fileName, stat, state,
         sizeBytes: stat.size,
         mtimeMs: stat.mtimeMs,
         firstSeenAt: new Date().toISOString(),
-        baseline: !hadState
+        baseline: !hadState && !includeNewFile
     };
-    return hadState;
+    return hadState || includeNewFile;
 }
 function isMarkdownScanStateFile(value) {
     if (!value || Array.isArray(value) || typeof value !== 'object') {
@@ -572,6 +889,17 @@ function isMarkdownScanStateFile(value) {
         typeof objectValue.firstSeenAt === 'string' &&
         typeof objectValue.baseline === 'boolean');
 }
+function isArtifactArchiveStateFile(value) {
+    if (!value || Array.isArray(value) || typeof value !== 'object') {
+        return false;
+    }
+    const objectValue = value;
+    return (typeof objectValue.sessionId === 'string' &&
+        typeof objectValue.targetRelativePath === 'string' &&
+        typeof objectValue.sizeBytes === 'number' &&
+        typeof objectValue.mtimeMs === 'number' &&
+        typeof objectValue.archivedAt === 'string');
+}
 function isArtifactRecord(value) {
     if (!value || Array.isArray(value) || typeof value !== 'object') {
         return false;
@@ -594,6 +922,7 @@ function artifactToJsonValue(item) {
         sizeBytes: item.sizeBytes,
         storageStatus: item.storageStatus,
         source: item.source,
+        sessionId: item.sessionId ?? null,
         previewable: item.previewable,
         createdAt: item.createdAt,
         updatedAt: item.updatedAt,
@@ -631,13 +960,20 @@ function expectString(value, fieldName) {
 function optionalTrimmedString(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
 }
-function normalizeArtifactFindFilters(params) {
+function normalizeArtifactFilters(params) {
     return {
+        sessionId: optionalTrimmedString(params.sessionId),
+        query: normalizeOptionalLowercaseString(params.query),
         category: normalizeArtifactCategory(optionalTrimmedString(params.category)),
         mimeType: normalizeOptionalLowercaseString(params.mimeType),
         fileName: normalizeOptionalLowercaseString(params.fileName),
         relativePathPrefix: normalizeRelativePath(optionalTrimmedString(params.relativePathPrefix)),
-        createdAfterMs: normalizeOptionalTimestamp(params.createdAfter),
+        createdAfterMs: normalizeOptionalTimestamp(params.createdAfter)
+    };
+}
+function normalizeArtifactFindFilters(params) {
+    return {
+        ...normalizeArtifactFilters(params),
         limit: normalizeArtifactLimit(params.limit)
     };
 }
@@ -680,14 +1016,36 @@ function normalizeArtifactLimit(value) {
     }
     return Math.min(50, Math.floor(value));
 }
-function matchesArtifactFindFilters(item, filters) {
+function normalizeArtifactGroupBy(value) {
+    const normalized = normalizeOptionalLowercaseString(value);
+    if (!normalized || normalized === 'none') {
+        return null;
+    }
+    if (normalized === 'session') {
+        return 'session';
+    }
+    if (normalized === 'category' || normalized === 'type') {
+        return 'category';
+    }
+    if (normalized === 'day' || normalized === 'date' || normalized === 'time') {
+        return 'day';
+    }
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, `Unsupported artifact groupBy: ${normalized}`);
+}
+function matchesArtifactFilters(item, filters) {
+    if (filters.sessionId && item.sessionId !== filters.sessionId) {
+        return false;
+    }
+    if (filters.query && !artifactMatchesQuery(item, filters.query)) {
+        return false;
+    }
     if (filters.category && item.category !== filters.category) {
         return false;
     }
     if (filters.mimeType && item.mimeType.toLowerCase() !== filters.mimeType) {
         return false;
     }
-    if (filters.fileName && item.fileName.toLowerCase() !== filters.fileName) {
+    if (filters.fileName && !item.fileName.toLowerCase().includes(filters.fileName)) {
         return false;
     }
     if (filters.relativePathPrefix && !item.relativePath.startsWith(filters.relativePathPrefix)) {
@@ -698,6 +1056,84 @@ function matchesArtifactFindFilters(item, filters) {
     }
     return true;
 }
+function matchesArtifactFindFilters(item, filters) {
+    return matchesArtifactFilters(item, filters);
+}
+function artifactMatchesQuery(item, query) {
+    const values = [
+        item.fileName,
+        item.relativePath,
+        item.category,
+        item.mimeType,
+        item.ext ?? '',
+        item.sessionId ?? ''
+    ];
+    return values.some((value) => value.toLowerCase().includes(query));
+}
+function buildArtifactGroups(items, groupBy) {
+    const groups = new Map();
+    for (const item of items) {
+        const { key, label } = resolveArtifactGroup(item, groupBy);
+        const group = groups.get(key) ?? { key, label, items: [] };
+        group.items.push(item);
+        groups.set(key, group);
+    }
+    return Array.from(groups.values())
+        .sort((left, right) => compareArtifactGroups(left, right, groupBy))
+        .map((group) => ({
+        key: group.key,
+        label: group.label,
+        count: group.items.length,
+        items: group.items.map(artifactToJsonValue)
+    }));
+}
+function resolveArtifactGroup(item, groupBy) {
+    if (groupBy === 'session') {
+        const sessionId = item.sessionId ?? null;
+        return {
+            key: sessionId ?? 'unassigned',
+            label: sessionId ?? 'Unassigned'
+        };
+    }
+    if (groupBy === 'category') {
+        return {
+            key: item.category,
+            label: item.category
+        };
+    }
+    const timestamp = Date.parse(item.createdAt);
+    if (Number.isNaN(timestamp)) {
+        return {
+            key: 'unknown',
+            label: 'Unknown'
+        };
+    }
+    const day = new Date(timestamp).toISOString().slice(0, 10);
+    return {
+        key: day,
+        label: day
+    };
+}
+function compareArtifactGroups(left, right, groupBy) {
+    if (groupBy === 'day') {
+        return right.key.localeCompare(left.key);
+    }
+    if (groupBy === 'category') {
+        return artifactCategorySortIndex(left.key) - artifactCategorySortIndex(right.key);
+    }
+    if (left.key === 'unassigned') {
+        return 1;
+    }
+    if (right.key === 'unassigned') {
+        return -1;
+    }
+    return left.key.localeCompare(right.key);
+}
+function artifactCategorySortIndex(value) {
+    const order = ['image', 'video', 'document', 'archive', 'other'];
+    const index = order.indexOf(value);
+    return index === -1 ? order.length : index;
+}
 function compareArtifactsByRecency(left, right) {
     const createdDelta = Date.parse(right.createdAt) - Date.parse(left.createdAt);
     if (createdDelta !== 0) {