@bbigbang/agent-node 0.1.0

package/dist/workspaceFs.js

@@ -0,0 +1,1020 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { TextDecoder } from 'node:util';
+import { gunzipSync, gzipSync } from 'node:zlib';
+import { resolveWorkspacePath } from '@bbigbang/runtime-acp';
+export const MAX_TEXT_PREVIEW_BYTES = 256 * 1024;
+export const MAX_IMAGE_PREVIEW_BYTES = 5 * 1024 * 1024;
+const WORKSPACE_ARCHIVE_MAX_ENTRY_COUNT = 10_000;
+const UTF8_FATAL_DECODER = new TextDecoder('utf-8', { fatal: true });
+function buildRoleScaffoldLine(agentName) {
+    const normalizedAgentName = agentName
+        ?.replace(/[\r\n]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!normalizedAgentName)
+        return '- Capture your current role and responsibilities here.';
+    return `- you are ${normalizedAgentName}. Capture your current role and responsibilities here.`;
+}
+const BEIJING_DATE_FORMATTER = new Intl.DateTimeFormat('en-CA', {
+    timeZone: 'Asia/Shanghai',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+});
+function getCurrentBeijingISOWeek() {
+    const parts = BEIJING_DATE_FORMATTER.formatToParts(new Date());
+    const getPart = (type) => Number(parts.find((part) => part.type === type)?.value);
+    const year = getPart('year');
+    const month = getPart('month');
+    const day = getPart('day');
+    const beijingDate = new Date(Date.UTC(year, month - 1, day));
+    const dayNum = beijingDate.getUTCDay() || 7;
+    beijingDate.setUTCDate(beijingDate.getUTCDate() + 4 - dayNum);
+    const yearStart = new Date(Date.UTC(beijingDate.getUTCFullYear(), 0, 1));
+    const weekNo = Math.ceil((((beijingDate.getTime() - yearStart.getTime()) / 86_400_000) + 1) / 7);
+    return `${beijingDate.getUTCFullYear()}-W${String(weekNo).padStart(2, '0')}`;
+}
+export class WorkspaceFsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function listWorkspaceDirectory(workspaceRoot, relativePath, options) {
+    if (options?.scaffold !== false)
+        ensureWorkspaceScaffold(workspaceRoot, options?.agentName);
+    const resolved = resolveRelativeWorkspacePath(workspaceRoot, relativePath);
+    const stat = fs.statSync(resolved, { throwIfNoEntry: false });
+    if (!stat)
+        throw new WorkspaceFsError('not_found', 'Path not found.');
+    if (!stat.isDirectory())
+        throw new WorkspaceFsError('not_directory', 'Path is not a directory.');
+    const candidates = fs
+        .readdirSync(resolved, { withFileTypes: true })
+        .map((entry) => {
+        const absoluteEntry = path.join(resolved, entry.name);
+        return classifyWorkspaceEntryCandidate(entry, absoluteEntry);
+    })
+        .sort((a, b) => {
+        if (a.kind !== b.kind)
+            return a.kind === 'directory' ? -1 : 1;
+        return a.dirent.name.localeCompare(b.dirent.name);
+    });
+    const { candidates: pageCandidates, page } = paginateWorkspaceEntryCandidates(candidates, {
+        cursor: options?.cursor,
+        limit: options?.limit,
+    });
+    const entries = pageCandidates.map((candidate) => workspaceEntryFromCandidate(workspaceRoot, candidate));
+    return {
+        relativePath: normalizeRelativePath(relativePath),
+        entries,
+        directoryPage: page,
+    };
+}
+export function readWorkspaceFile(workspaceRoot, relativePath, options) {
+    if (options?.scaffold !== false)
+        ensureWorkspaceScaffold(workspaceRoot, options?.agentName);
+    const resolved = resolveRelativeWorkspacePath(workspaceRoot, relativePath);
+    const stat = fs.statSync(resolved, { throwIfNoEntry: false });
+    if (!stat)
+        throw new WorkspaceFsError('not_found', 'Path not found.');
+    if (!stat.isFile())
+        throw new WorkspaceFsError('not_file', 'Path is not a file.');
+    const chunkRequest = normalizeFileChunkRequest(options);
+    const mimeType = getPreviewMimeType(resolved);
+    const isImage = mimeType.startsWith('image/');
+    if (chunkRequest && isImage) {
+        throw new WorkspaceFsError('invalid_request', 'Chunked preview is only supported for text files.');
+    }
+    if (chunkRequest) {
+        return readWorkspaceTextChunk(resolved, relativePath, stat, mimeType, chunkRequest);
+    }
+    const maxPreviewBytes = isImage ? MAX_IMAGE_PREVIEW_BYTES : MAX_TEXT_PREVIEW_BYTES;
+    if (stat.size > maxPreviewBytes) {
+        throw new WorkspaceFsError('file_too_large', `File exceeds preview limit (${maxPreviewBytes} bytes).`);
+    }
+    const contentBuffer = fs.readFileSync(resolved);
+    if (isImage) {
+        return {
+            relativePath: normalizeRelativePath(relativePath),
+            content: `data:${mimeType};base64,${contentBuffer.toString('base64')}`,
+            mimeType,
+            size: stat.size,
+            modifiedAt: Math.floor(stat.mtimeMs),
+        };
+    }
+    if (looksBinary(contentBuffer)) {
+        throw new WorkspaceFsError('binary_file', 'Binary files are not supported for preview.');
+    }
+    return {
+        relativePath: normalizeRelativePath(relativePath),
+        content: contentBuffer.toString('utf8'),
+        mimeType,
+        size: stat.size,
+        modifiedAt: Math.floor(stat.mtimeMs),
+    };
+}
+export function createWorkspaceDirectoryArchive(workspaceRoot, relativePath, options = {}) {
+    const maxBytes = normalizeArchiveMaxBytes(options.maxBytes);
+    const root = resolveRelativeWorkspacePath(workspaceRoot, relativePath);
+    const rootStat = fs.lstatSync(root, { throwIfNoEntry: false });
+    if (!rootStat)
+        throw new WorkspaceFsError('not_found', 'Path not found.');
+    if (rootStat.isSymbolicLink()) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Symlink archives are not supported.');
+    }
+    if (!rootStat.isDirectory()) {
+        throw new WorkspaceFsError('not_directory', 'Path is not a directory.');
+    }
+    const entries = [];
+    let byteSize = 0;
+    let fileCount = 0;
+    const pushEntry = (entry) => {
+        if (entries.length >= WORKSPACE_ARCHIVE_MAX_ENTRY_COUNT) {
+            throw new WorkspaceFsError('file_too_large', `Archive contains too many entries (${WORKSPACE_ARCHIVE_MAX_ENTRY_COUNT}).`);
+        }
+        entries.push(entry);
+    };
+    const visit = (absoluteDirectory, archiveDirectoryPath) => {
+        const directoryStat = fs.lstatSync(absoluteDirectory, { throwIfNoEntry: false });
+        if (!directoryStat)
+            throw new WorkspaceFsError('not_found', 'Path not found.');
+        if (directoryStat.isSymbolicLink()) {
+            throw new WorkspaceFsError('path_outside_workspace', 'Symlink archives are not supported.');
+        }
+        if (!directoryStat.isDirectory()) {
+            throw new WorkspaceFsError('not_directory', 'Path is not a directory.');
+        }
+        if (archiveDirectoryPath) {
+            pushEntry({
+                kind: 'directory',
+                path: archiveDirectoryPath,
+                mode: directoryStat.mode & 0o777,
+            });
+        }
+        for (const dirent of fs.readdirSync(absoluteDirectory, { withFileTypes: true }).sort(compareDirents)) {
+            const absoluteChild = path.join(absoluteDirectory, dirent.name);
+            const archiveChildPath = archiveDirectoryPath
+                ? `${archiveDirectoryPath}/${dirent.name}`
+                : dirent.name;
+            const childStat = fs.lstatSync(absoluteChild, { throwIfNoEntry: false });
+            if (!childStat)
+                continue;
+            if (childStat.isSymbolicLink()) {
+                throw new WorkspaceFsError('path_outside_workspace', 'Symlink archives are not supported.');
+            }
+            if (childStat.isDirectory()) {
+                visit(absoluteChild, archiveChildPath);
+                continue;
+            }
+            if (!childStat.isFile()) {
+                throw new WorkspaceFsError('not_file', 'Only regular files are supported in workspace archives.');
+            }
+            byteSize += childStat.size;
+            if (byteSize > maxBytes) {
+                throw new WorkspaceFsError('file_too_large', `Archive exceeds size limit (${maxBytes} bytes).`);
+            }
+            const content = fs.readFileSync(absoluteChild);
+            pushEntry({
+                kind: 'file',
+                path: archiveChildPath,
+                mode: childStat.mode & 0o777,
+                contentBase64: content.toString('base64'),
+            });
+            fileCount += 1;
+        }
+    };
+    visit(root, '');
+    const payload = { version: 1, entries };
+    const payloadBuffer = Buffer.from(JSON.stringify(payload), 'utf8');
+    const maxArchiveBytes = normalizeArchiveSerializedMaxBytes(maxBytes);
+    if (payloadBuffer.length > maxArchiveBytes) {
+        throw new WorkspaceFsError('file_too_large', `Archive metadata exceeds size limit (${maxArchiveBytes} bytes).`);
+    }
+    const compressed = gzipSync(payloadBuffer);
+    if (compressed.length > maxArchiveBytes) {
+        throw new WorkspaceFsError('file_too_large', `Archive exceeds serialized size limit (${maxArchiveBytes} bytes).`);
+    }
+    return {
+        relativePath: normalizeRelativePath(relativePath),
+        archiveBase64: compressed.toString('base64'),
+        byteSize,
+        fileCount,
+    };
+}
+export function extractWorkspaceDirectoryArchive(workspaceRoot, relativePath, archiveBase64, options = {}) {
+    const maxBytes = normalizeArchiveMaxBytes(options.maxBytes);
+    const resolvedTarget = resolveRelativeWorkspacePath(workspaceRoot, relativePath);
+    assertWorkspaceMutationParentPath(workspaceRoot, resolvedTarget);
+    const existingTarget = fs.lstatSync(resolvedTarget, { throwIfNoEntry: false });
+    if (existingTarget && !options.overwrite) {
+        throw new WorkspaceFsError('invalid_request', 'Target path already exists.');
+    }
+    if (existingTarget?.isSymbolicLink()) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Refusing to extract over a symlink path.');
+    }
+    const payload = decodeWorkspaceArchivePayload(archiveBase64, maxBytes);
+    if (existingTarget && options.overwrite) {
+        assertWorkspaceMutationPath(workspaceRoot, resolvedTarget);
+        fs.rmSync(resolvedTarget, { recursive: true, force: true });
+    }
+    fs.mkdirSync(resolvedTarget, { recursive: true });
+    assertWorkspaceMutationPath(workspaceRoot, resolvedTarget);
+    let byteSize = 0;
+    let fileCount = 0;
+    for (const entry of payload.entries) {
+        const normalizedEntryPath = normalizeArchiveEntryPath(entry.path);
+        const absoluteEntryPath = path.resolve(resolvedTarget, normalizedEntryPath);
+        assertArchiveEntryInsideTarget(resolvedTarget, absoluteEntryPath);
+        if (entry.kind === 'directory') {
+            fs.mkdirSync(absoluteEntryPath, { recursive: true });
+            fs.chmodSync(absoluteEntryPath, normalizeArchiveMode(entry.mode, 0o755));
+            continue;
+        }
+        fs.mkdirSync(path.dirname(absoluteEntryPath), { recursive: true });
+        const content = decodeArchiveEntryContent(entry.contentBase64);
+        byteSize += content.length;
+        if (byteSize > maxBytes) {
+            throw new WorkspaceFsError('file_too_large', `Archive exceeds size limit (${maxBytes} bytes).`);
+        }
+        fs.writeFileSync(absoluteEntryPath, content);
+        fs.chmodSync(absoluteEntryPath, normalizeArchiveMode(entry.mode, 0o644));
+        fileCount += 1;
+    }
+    return {
+        relativePath: normalizeRelativePath(relativePath),
+        byteSize,
+        fileCount,
+    };
+}
+export function deleteWorkspaceFile(workspaceRoot, relativePath) {
+    const resolved = resolveRelativeWorkspacePath(workspaceRoot, relativePath);
+    assertWorkspaceMutationPath(workspaceRoot, resolved);
+    const stat = fs.statSync(resolved, { throwIfNoEntry: false });
+    if (!stat)
+        throw new WorkspaceFsError('not_found', 'Path not found.');
+    if (!stat.isFile())
+        throw new WorkspaceFsError('not_file', 'Path is not a file.');
+    fs.unlinkSync(resolved);
+    return { relativePath: normalizeRelativePath(relativePath) };
+}
+export function deleteWorkspacePath(workspaceRoot, relativePath, options) {
+    const normalized = normalizeRelativePath(relativePath);
+    if (!normalized) {
+        throw new WorkspaceFsError('invalid_request', 'Refusing to delete workspace root.');
+    }
+    const resolved = resolveRelativeWorkspacePath(workspaceRoot, normalized);
+    assertWorkspaceMutationPath(workspaceRoot, resolved);
+    const stat = fs.lstatSync(resolved, { throwIfNoEntry: false });
+    if (!stat)
+        throw new WorkspaceFsError('not_found', 'Path not found.');
+    if (stat.isDirectory() && options?.recursive !== true) {
+        throw new WorkspaceFsError('invalid_request', 'Path is a directory. Set recursive=true to delete directories.');
+    }
+    fs.rmSync(resolved, { recursive: stat.isDirectory(), force: false });
+    return { relativePath: normalized };
+}
+function decodeBase64WorkspaceContent(content) {
+    const compact = content.replace(/\s+/g, '');
+    if (!compact)
+        return Buffer.alloc(0);
+    if (compact.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(compact)) {
+        throw new WorkspaceFsError('invalid_request', 'Invalid base64 content.');
+    }
+    const decoded = Buffer.from(compact, 'base64');
+    if (decoded.toString('base64') !== compact) {
+        throw new WorkspaceFsError('invalid_request', 'Invalid base64 content.');
+    }
+    return decoded;
+}
+function decodeArchiveEntryContent(content) {
+    const compact = content.replace(/\s+/g, '');
+    if (!compact)
+        return Buffer.alloc(0);
+    if (compact.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(compact)) {
+        throw new WorkspaceFsError('invalid_request', 'Invalid archive file content.');
+    }
+    return Buffer.from(compact, 'base64');
+}
+function decodeWorkspaceArchivePayload(archiveBase64, maxBytes) {
+    const archive = decodeArchiveEntryContent(archiveBase64);
+    const maxArchiveBytes = normalizeArchiveSerializedMaxBytes(maxBytes);
+    if (archive.length > maxArchiveBytes) {
+        throw new WorkspaceFsError('file_too_large', `Archive exceeds serialized size limit (${maxArchiveBytes} bytes).`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(gunzipSync(archive, { maxOutputLength: maxArchiveBytes }).toString('utf8'));
+    }
+    catch {
+        throw new WorkspaceFsError('invalid_request', 'Invalid workspace archive.');
+    }
+    if (!parsed || typeof parsed !== 'object' || parsed.version !== 1 || !Array.isArray(parsed.entries)) {
+        throw new WorkspaceFsError('invalid_request', 'Invalid workspace archive.');
+    }
+    const entries = [];
+    for (const rawEntry of parsed.entries) {
+        if (entries.length >= WORKSPACE_ARCHIVE_MAX_ENTRY_COUNT) {
+            throw new WorkspaceFsError('file_too_large', `Archive contains too many entries (${WORKSPACE_ARCHIVE_MAX_ENTRY_COUNT}).`);
+        }
+        if (!rawEntry || typeof rawEntry !== 'object') {
+            throw new WorkspaceFsError('invalid_request', 'Invalid workspace archive entry.');
+        }
+        const record = rawEntry;
+        const kind = record.kind;
+        const entryPath = typeof record.path === 'string' ? normalizeArchiveEntryPath(record.path) : null;
+        const mode = typeof record.mode === 'number' && Number.isInteger(record.mode) ? record.mode : null;
+        if (!entryPath || mode == null) {
+            throw new WorkspaceFsError('invalid_request', 'Invalid workspace archive entry.');
+        }
+        if (kind === 'directory') {
+            entries.push({ kind, path: entryPath, mode });
+            continue;
+        }
+        if (kind === 'file' && typeof record.contentBase64 === 'string') {
+            entries.push({ kind, path: entryPath, mode, contentBase64: record.contentBase64 });
+            continue;
+        }
+        throw new WorkspaceFsError('invalid_request', 'Invalid workspace archive entry.');
+    }
+    return { version: 1, entries };
+}
+function normalizeArchiveEntryPath(value) {
+    const normalized = value.replace(/\\/g, '/').replace(/^\/+/, '').trim();
+    const posixNormalized = path.posix.normalize(normalized).replace(/^\.\/+/, '');
+    if (!posixNormalized || posixNormalized === '.' || posixNormalized === '..' || posixNormalized.startsWith('../') || path.posix.isAbsolute(posixNormalized)) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Archive entry escapes target path.');
+    }
+    return posixNormalized;
+}
+function assertArchiveEntryInsideTarget(resolvedTarget, absoluteEntryPath) {
+    const relative = path.relative(path.resolve(resolvedTarget), path.resolve(absoluteEntryPath));
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Archive entry escapes target path.');
+    }
+}
+function normalizeArchiveMaxBytes(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 25 * 1024 * 1024;
+    return Math.min(100 * 1024 * 1024, Math.max(1, Math.floor(value)));
+}
+function normalizeArchiveSerializedMaxBytes(maxBytes) {
+    return Math.max(8 * 1024, maxBytes * 4);
+}
+function normalizeArchiveMode(value, fallback) {
+    if (!Number.isInteger(value))
+        return fallback;
+    const mode = value & 0o777;
+    return mode > 0 ? mode : fallback;
+}
+function normalizeFileChunkRequest(options) {
+    if (options?.offset === undefined && options?.limit === undefined)
+        return null;
+    const offset = options.offset ?? 0;
+    const limit = options.limit ?? MAX_TEXT_PREVIEW_BYTES;
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new WorkspaceFsError('invalid_request', 'offset must be a non-negative integer.');
+    }
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_TEXT_PREVIEW_BYTES) {
+        throw new WorkspaceFsError('invalid_request', `limit must be between 1 and ${MAX_TEXT_PREVIEW_BYTES}.`);
+    }
+    return { offset, limit };
+}
+function readWorkspaceTextChunk(resolved, relativePath, stat, mimeType, chunkRequest) {
+    if (chunkRequest.offset > stat.size) {
+        throw new WorkspaceFsError('invalid_request', 'offset is beyond the end of the file.');
+    }
+    const readLength = Math.min(chunkRequest.limit, Math.max(0, stat.size - chunkRequest.offset));
+    const contentBuffer = Buffer.alloc(readLength);
+    const fd = fs.openSync(resolved, 'r');
+    try {
+        fs.readSync(fd, contentBuffer, 0, readLength, chunkRequest.offset);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    if (looksBinary(contentBuffer)) {
+        throw new WorkspaceFsError('binary_file', 'Binary files are not supported for preview.');
+    }
+    const safeLength = findUtf8SafeLength(contentBuffer);
+    const safeBuffer = safeLength === contentBuffer.length ? contentBuffer : contentBuffer.subarray(0, safeLength);
+    const nextOffset = chunkRequest.offset + safeBuffer.length;
+    return {
+        relativePath: normalizeRelativePath(relativePath),
+        content: safeBuffer.toString('utf8'),
+        mimeType,
+        size: stat.size,
+        modifiedAt: Math.floor(stat.mtimeMs),
+        offset: chunkRequest.offset,
+        limit: chunkRequest.limit,
+        nextOffset: nextOffset < stat.size ? nextOffset : null,
+        hasMore: nextOffset < stat.size,
+    };
+}
+function findUtf8SafeLength(buffer) {
+    if (buffer.length === 0)
+        return 0;
+    for (let length = buffer.length; length >= Math.max(1, buffer.length - 3); length -= 1) {
+        try {
+            UTF8_FATAL_DECODER.decode(buffer.subarray(0, length));
+            return length;
+        }
+        catch {
+            // Keep trimming up to one UTF-8 sequence so chunk boundaries do not split a code point.
+        }
+    }
+    return buffer.length;
+}
+export function readExactPath(absolutePath, options = {}) {
+    if (!path.isAbsolute(absolutePath)) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Path must be absolute.');
+    }
+    const resolved = path.resolve(absolutePath);
+    if (options.allowedRoot) {
+        const resolvedRoot = path.resolve(options.allowedRoot);
+        const relative = path.relative(resolvedRoot, resolved);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            throw new WorkspaceFsError('path_outside_workspace', 'Path escapes allowed root.');
+        }
+    }
+    const stat = fs.lstatSync(resolved, { throwIfNoEntry: false });
+    if (!stat)
+        throw new WorkspaceFsError('not_found', 'Path not found.');
+    if (stat.isSymbolicLink()) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Symlink previews require direct access to the resolved target.');
+    }
+    assertRealPathInsideAllowedRoot(resolved, options.allowedRoot, options.trustedRoot);
+    if (stat.isDirectory()) {
+        const sortedEntries = fs
+            .readdirSync(resolved, { withFileTypes: true })
+            .filter((entry) => !entry.isSymbolicLink())
+            .sort(compareDirents);
+        const { dirents, page } = paginateDirents(sortedEntries, options);
+        const entries = dirents
+            .map((entry) => {
+            const absoluteEntry = path.join(resolved, entry.name);
+            const entryStat = fs.lstatSync(absoluteEntry, { throwIfNoEntry: false });
+            if (!entryStat || entryStat.isSymbolicLink())
+                return null;
+            return {
+                name: entry.name,
+                path: absoluteEntry,
+                kind: entryStat.isDirectory() ? 'directory' : 'file',
+                size: entryStat.isDirectory() ? null : entryStat.size,
+                modifiedAt: entryStat.mtimeMs ? Math.floor(entryStat.mtimeMs) : null,
+            };
+        })
+            .filter((entry) => entry != null);
+        return {
+            absolutePath: resolved,
+            kind: 'directory',
+            entries,
+            directoryPage: page,
+            modifiedAt: Math.floor(stat.mtimeMs),
+        };
+    }
+    if (!stat.isFile())
+        throw new WorkspaceFsError('not_file', 'Path is not a file.');
+    const chunkRequest = normalizeFileChunkRequest({ offset: options.offset, limit: options.limit });
+    const mimeType = getPreviewMimeType(resolved);
+    const isImage = mimeType.startsWith('image/');
+    if (options.rawContentBase64 && chunkRequest) {
+        throw new WorkspaceFsError('invalid_request', 'Raw exact path reads do not support chunk offsets.');
+    }
+    if (chunkRequest && isImage) {
+        throw new WorkspaceFsError('invalid_request', 'Chunked preview is only supported for text files.');
+    }
+    if (chunkRequest) {
+        const chunk = readWorkspaceTextChunk(resolved, resolved, stat, mimeType, chunkRequest);
+        return {
+            absolutePath: resolved,
+            kind: 'file',
+            content: chunk.content,
+            mimeType: chunk.mimeType,
+            size: chunk.size,
+            modifiedAt: chunk.modifiedAt,
+            offset: chunk.offset,
+            limit: chunk.limit,
+            nextOffset: chunk.nextOffset,
+            hasMore: chunk.hasMore,
+        };
+    }
+    const maxPreviewBytes = options.maxPreviewBytes ?? (isImage ? MAX_IMAGE_PREVIEW_BYTES : MAX_TEXT_PREVIEW_BYTES);
+    if (stat.size > maxPreviewBytes) {
+        throw new WorkspaceFsError('file_too_large', `File exceeds preview limit (${maxPreviewBytes} bytes).`);
+    }
+    const contentBuffer = fs.readFileSync(resolved);
+    if (options.rawContentBase64) {
+        return {
+            absolutePath: resolved,
+            kind: 'file',
+            content: contentBuffer.toString('base64'),
+            mimeType,
+            size: stat.size,
+            modifiedAt: Math.floor(stat.mtimeMs),
+            rawContentBase64: true,
+        };
+    }
+    if (isImage) {
+        return {
+            absolutePath: resolved,
+            kind: 'file',
+            content: `data:${mimeType};base64,${contentBuffer.toString('base64')}`,
+            mimeType,
+            size: stat.size,
+            modifiedAt: Math.floor(stat.mtimeMs),
+        };
+    }
+    if (looksBinary(contentBuffer)) {
+        throw new WorkspaceFsError('binary_file', 'Binary files are not supported for preview.');
+    }
+    return {
+        absolutePath: resolved,
+        kind: 'file',
+        content: contentBuffer.toString('utf8'),
+        mimeType,
+        size: stat.size,
+        modifiedAt: Math.floor(stat.mtimeMs),
+    };
+}
+export function suggestDirectoryPaths(query, options = {}) {
+    const normalizedQuery = query.trim();
+    if (!normalizedQuery) {
+        throw new WorkspaceFsError('invalid_request', 'Path query is required.');
+    }
+    if (/[\r\n]/.test(normalizedQuery)) {
+        throw new WorkspaceFsError('invalid_request', 'Path query must not contain newlines.');
+    }
+    if (!path.isAbsolute(normalizedQuery)) {
+        throw new WorkspaceFsError('invalid_request', 'Path query must be absolute.');
+    }
+    const limit = normalizePathSuggestionLimit(options.limit);
+    const queryEndsWithSeparator = /[\\/]$/.test(normalizedQuery);
+    const parentPath = queryEndsWithSeparator
+        ? path.resolve(normalizedQuery)
+        : path.dirname(normalizedQuery);
+    const prefix = queryEndsWithSeparator ? '' : path.basename(normalizedQuery);
+    const parentStat = fs.lstatSync(parentPath, { throwIfNoEntry: false });
+    if (!parentStat)
+        throw new WorkspaceFsError('not_found', 'Parent directory not found.');
+    if (parentStat.isSymbolicLink()) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Symlink directory suggestions are not supported.');
+    }
+    if (!parentStat.isDirectory()) {
+        throw new WorkspaceFsError('not_directory', 'Parent path is not a directory.');
+    }
+    const normalizedPrefix = prefix.toLocaleLowerCase();
+    const suggestions = fs
+        .readdirSync(parentPath, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.isSymbolicLink())
+        .filter((entry) => !normalizedPrefix || entry.name.toLocaleLowerCase().startsWith(normalizedPrefix))
+        .sort(compareDirents)
+        .slice(0, limit)
+        .map((entry) => {
+        const suggestionPath = path.join(parentPath, entry.name);
+        return {
+            path: suggestionPath,
+            name: entry.name,
+            parentPath,
+            isGitRepo: isGitRepositoryDirectory(suggestionPath),
+        };
+    });
+    return { query: normalizedQuery, suggestions };
+}
+export function statExactPathRawStream(absolutePath, options = {}) {
+    const { resolved, stat } = statExactFilePath(absolutePath, options);
+    const mimeType = getPreviewMimeType(resolved);
+    if (!mimeType.startsWith('image/')) {
+        throw new WorkspaceFsError('binary_file', 'Raw streaming previews are only supported for image files.');
+    }
+    if (stat.size > MAX_IMAGE_PREVIEW_BYTES) {
+        throw new WorkspaceFsError('file_too_large', `File exceeds preview limit (${MAX_IMAGE_PREVIEW_BYTES} bytes).`);
+    }
+    return {
+        absolutePath: resolved,
+        mimeType,
+        size: stat.size,
+        modifiedAt: Math.floor(stat.mtimeMs),
+    };
+}
+export function createExactPathReadStream(absolutePath) {
+    const { resolved } = statExactFilePath(absolutePath);
+    return fs.createReadStream(resolved, { highWaterMark: 64 * 1024 });
+}
+function statExactFilePath(absolutePath, options = {}) {
+    if (!path.isAbsolute(absolutePath)) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Path must be absolute.');
+    }
+    const resolved = path.resolve(absolutePath);
+    if (options.allowedRoot) {
+        const resolvedRoot = path.resolve(options.allowedRoot);
+        const relative = path.relative(resolvedRoot, resolved);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            throw new WorkspaceFsError('path_outside_workspace', 'Path escapes allowed root.');
+        }
+    }
+    const stat = fs.lstatSync(resolved, { throwIfNoEntry: false });
+    if (!stat)
+        throw new WorkspaceFsError('not_found', 'Path not found.');
+    if (stat.isSymbolicLink()) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Symlink previews require direct access to the resolved target.');
+    }
+    assertRealPathInsideAllowedRoot(resolved, options.allowedRoot, options.trustedRoot);
+    if (!stat.isFile())
+        throw new WorkspaceFsError('not_file', 'Path is not a file.');
+    return { resolved, stat };
+}
+function assertRealPathInsideAllowedRoot(resolvedPath, allowedRoot, trustedRoot) {
+    if (!allowedRoot)
+        return;
+    let realRoot;
+    let realTarget;
+    let realTrustedRoot = null;
+    try {
+        realRoot = fs.realpathSync(path.resolve(allowedRoot));
+        realTarget = fs.realpathSync(resolvedPath);
+        if (trustedRoot) {
+            realTrustedRoot = fs.realpathSync(path.resolve(trustedRoot));
+        }
+    }
+    catch {
+        throw new WorkspaceFsError('not_found', 'Path not found.');
+    }
+    if (realTrustedRoot) {
+        const rootRelativeToTrustedRoot = path.relative(realTrustedRoot, realRoot);
+        if (rootRelativeToTrustedRoot.startsWith('..') || path.isAbsolute(rootRelativeToTrustedRoot)) {
+            throw new WorkspaceFsError('path_outside_workspace', 'Allowed root escapes trusted root.');
+        }
+    }
+    const relativeRealPath = path.relative(realRoot, realTarget);
+    if (relativeRealPath.startsWith('..') || path.isAbsolute(relativeRealPath)) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Path escapes allowed root.');
+    }
+}
+const DIRECTORY_CURSOR_PREFIX = 'k:';
+function classifyWorkspaceEntryCandidate(entry, absolutePath) {
+    const isSymlink = entry.isSymbolicLink();
+    if (isSymlink) {
+        const targetStat = fs.statSync(absolutePath, { throwIfNoEntry: false });
+        return {
+            dirent: entry,
+            absolutePath,
+            kind: targetStat?.isDirectory() ? 'directory' : 'file',
+            isSymlink,
+        };
+    }
+    return {
+        dirent: entry,
+        absolutePath,
+        kind: entry.isDirectory() ? 'directory' : 'file',
+        isSymlink,
+    };
+}
+function workspaceEntryFromCandidate(workspaceRoot, candidate) {
+    const stat = fs.statSync(candidate.absolutePath, { throwIfNoEntry: false });
+    return {
+        name: candidate.dirent.name,
+        path: toRelativeWorkspacePath(workspaceRoot, candidate.absolutePath),
+        kind: candidate.kind,
+        size: candidate.kind === 'directory' ? null : (stat?.size ?? null),
+        modifiedAt: stat?.mtimeMs ? Math.floor(stat.mtimeMs) : null,
+        ...(candidate.isSymlink ? { isSymlink: true } : {}),
+    };
+}
+function paginateWorkspaceEntryCandidates(candidates, options) {
+    const limit = normalizeWorkbenchDirectoryLimit(options.limit);
+    const offset = parseWorkspaceEntryCursor(options.cursor, candidates);
+    const pageCandidates = candidates.slice(offset, offset + limit);
+    const nextOffset = offset + pageCandidates.length;
+    const hasMore = nextOffset < candidates.length;
+    return {
+        candidates: pageCandidates,
+        page: {
+            nextCursor: hasMore && pageCandidates.length ? encodeWorkspaceEntryCursor(pageCandidates[pageCandidates.length - 1]) : null,
+            hasMore,
+            limit,
+        },
+    };
+}
+function paginateDirents(dirents, options) {
+    const limit = normalizeDirectoryLimit(options.limit);
+    const offset = parseDirectoryCursor(options.cursor, dirents);
+    const pageDirents = dirents.slice(offset, offset + limit);
+    const nextOffset = offset + pageDirents.length;
+    const hasMore = nextOffset < dirents.length;
+    return {
+        dirents: pageDirents,
+        page: {
+            nextCursor: hasMore && pageDirents.length ? encodeDirectoryCursor(pageDirents[pageDirents.length - 1]) : null,
+            hasMore,
+            limit,
+        },
+    };
+}
+function compareDirents(left, right) {
+    return compareDirectoryEntryKeys(direntKind(left), left.name, direntKind(right), right.name);
+}
+function direntKind(entry) {
+    return entry.isDirectory() ? 'directory' : 'file';
+}
+function compareDirectoryEntryKeys(leftKind, leftName, rightKind, rightName) {
+    if (leftKind !== rightKind)
+        return leftKind === 'directory' ? -1 : 1;
+    return leftName.localeCompare(rightName);
+}
+function normalizePathSuggestionLimit(limit) {
+    if (typeof limit !== 'number' || !Number.isFinite(limit))
+        return 20;
+    return Math.min(100, Math.max(1, Math.floor(limit)));
+}
+function isGitRepositoryDirectory(directoryPath) {
+    try {
+        return fs.lstatSync(path.join(directoryPath, '.git'), { throwIfNoEntry: false })?.isDirectory() ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+function encodeDirectoryCursor(entry) {
+    const payload = { kind: direntKind(entry), name: entry.name };
+    return `${DIRECTORY_CURSOR_PREFIX}${Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')}`;
+}
+function normalizeDirectoryLimit(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 100;
+    return Math.min(200, Math.max(1, Math.floor(value)));
+}
+function normalizeWorkbenchDirectoryLimit(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 500;
+    return Math.min(1000, Math.max(1, Math.floor(value)));
+}
+function parseWorkspaceEntryCursor(value, candidates) {
+    const decoded = decodeDirectoryCursor(value);
+    if (!decoded)
+        return 0;
+    const index = candidates.findIndex((entry) => compareDirectoryEntryKeys(entry.kind, entry.dirent.name, decoded.kind, decoded.name) > 0);
+    return index === -1 ? candidates.length : index;
+}
+function parseDirectoryCursor(value, dirents) {
+    if (!value)
+        return 0;
+    const decoded = decodeDirectoryCursor(value);
+    if (decoded) {
+        const index = dirents.findIndex((entry) => compareDirectoryEntryKeys(direntKind(entry), entry.name, decoded.kind, decoded.name) > 0);
+        return index === -1 ? dirents.length : index;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return 0;
+    return parsed;
+}
+function encodeWorkspaceEntryCursor(entry) {
+    const payload = { kind: entry.kind, name: entry.dirent.name };
+    return `${DIRECTORY_CURSOR_PREFIX}${Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')}`;
+}
+function decodeDirectoryCursor(value) {
+    if (!value?.startsWith(DIRECTORY_CURSOR_PREFIX))
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(value.slice(DIRECTORY_CURSOR_PREFIX.length), 'base64url').toString('utf8'));
+        const cursorKind = parsed.kind;
+        const cursorName = parsed.name;
+        if ((cursorKind === 'directory' || cursorKind === 'file') && typeof cursorName === 'string') {
+            return { kind: cursorKind, name: cursorName };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export function resetWorkspaceDirectory(workspaceRoot, agentName) {
+    const resolvedRoot = path.resolve(workspaceRoot);
+    if (resolvedRoot === path.parse(resolvedRoot).root) {
+        throw new WorkspaceFsError('io_error', 'Refusing to reset filesystem root.');
+    }
+    fs.mkdirSync(resolvedRoot, { recursive: true });
+    for (const entry of fs.readdirSync(resolvedRoot, { withFileTypes: true })) {
+        const target = path.join(resolvedRoot, entry.name);
+        fs.rmSync(target, { recursive: true, force: true });
+    }
+    ensureWorkspaceScaffold(resolvedRoot, agentName);
+}
+export function writeWorkspaceFile(workspaceRoot, relativePath, content, mode, options) {
+    if (options?.scaffold !== false)
+        ensureWorkspaceScaffold(workspaceRoot, options?.agentName);
+    const resolved = resolveRelativeWorkspacePath(workspaceRoot, relativePath);
+    assertWorkspaceMutationParentPath(workspaceRoot, resolved);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    assertWorkspaceMutationPath(workspaceRoot, resolved);
+    const existing = fs.statSync(resolved, { throwIfNoEntry: false });
+    if (existing?.isDirectory()) {
+        throw new WorkspaceFsError('not_file', 'Path is a directory.');
+    }
+    const contentEncoding = options?.contentEncoding ?? 'utf8';
+    const payload = contentEncoding === 'base64'
+        ? decodeBase64WorkspaceContent(content)
+        : content;
+    if (mode === 'append') {
+        fs.appendFileSync(resolved, payload, contentEncoding === 'base64' ? undefined : 'utf8');
+    }
+    else {
+        fs.writeFileSync(resolved, payload, contentEncoding === 'base64' ? undefined : 'utf8');
+    }
+    const stat = fs.statSync(resolved, { throwIfNoEntry: false });
+    return {
+        relativePath: normalizeRelativePath(relativePath),
+        modifiedAt: stat?.mtimeMs ? Math.floor(stat.mtimeMs) : null,
+    };
+}
+function resolveRelativeWorkspacePath(workspaceRoot, relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    const absoluteRequested = normalized
+        ? path.resolve(workspaceRoot, normalized)
+        : path.resolve(workspaceRoot);
+    try {
+        return resolveWorkspacePath(workspaceRoot, absoluteRequested);
+    }
+    catch {
+        throw new WorkspaceFsError('path_outside_workspace', 'Path escapes workspace root.');
+    }
+}
+function assertWorkspaceMutationPath(workspaceRoot, resolvedPath) {
+    let workspaceRealPath;
+    let parentRealPath;
+    try {
+        workspaceRealPath = fs.realpathSync(workspaceRoot);
+        parentRealPath = fs.realpathSync(path.dirname(resolvedPath));
+    }
+    catch {
+        throw new WorkspaceFsError('not_found', 'Path not found.');
+    }
+    const parentRelative = path.relative(workspaceRealPath, parentRealPath);
+    if (parentRelative === '..' || parentRelative.startsWith(`..${path.sep}`) || path.isAbsolute(parentRelative)) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Path escapes workspace root.');
+    }
+    const existing = fs.lstatSync(resolvedPath, { throwIfNoEntry: false });
+    if (existing?.isSymbolicLink()) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Refusing to mutate a symlink path.');
+    }
+}
+function assertWorkspaceMutationParentPath(workspaceRoot, resolvedPath) {
+    let workspaceRealPath;
+    try {
+        workspaceRealPath = fs.realpathSync(workspaceRoot);
+    }
+    catch {
+        throw new WorkspaceFsError('not_found', 'Path not found.');
+    }
+    const workspaceAbsolute = path.resolve(workspaceRoot);
+    const parentRelative = path.relative(workspaceAbsolute, path.dirname(resolvedPath));
+    if (parentRelative === '..' || parentRelative.startsWith(`..${path.sep}`) || path.isAbsolute(parentRelative)) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Path escapes workspace root.');
+    }
+    let cursor = workspaceAbsolute;
+    for (const part of parentRelative.split(path.sep).filter(Boolean)) {
+        cursor = path.join(cursor, part);
+        const existing = fs.lstatSync(cursor, { throwIfNoEntry: false });
+        if (!existing)
+            return;
+        if (existing.isSymbolicLink()) {
+            throw new WorkspaceFsError('path_outside_workspace', 'Refusing to mutate through a symlink path.');
+        }
+        let cursorRealPath;
+        try {
+            cursorRealPath = fs.realpathSync(cursor);
+        }
+        catch {
+            throw new WorkspaceFsError('not_found', 'Path not found.');
+        }
+        const realRelative = path.relative(workspaceRealPath, cursorRealPath);
+        if (realRelative === '..' || realRelative.startsWith(`..${path.sep}`) || path.isAbsolute(realRelative)) {
+            throw new WorkspaceFsError('path_outside_workspace', 'Path escapes workspace root.');
+        }
+    }
+}
+/** One-time migration: move legacy flat work-log to the weekly directory structure. */
+export function migrateWorkspaceLegacyFiles(workspaceRoot) {
+    const legacyWorkLogPath = path.join(workspaceRoot, 'notes', 'work-log.md');
+    const legacyDestPath = path.join(workspaceRoot, 'notes', 'work-log', 'legacy.md');
+    if (!fs.existsSync(legacyWorkLogPath))
+        return;
+    if (!fs.existsSync(legacyDestPath)) {
+        fs.renameSync(legacyWorkLogPath, legacyDestPath);
+    }
+    else {
+        // legacy.md already exists; append orphan content rather than discard it
+        const orphan = fs.readFileSync(legacyWorkLogPath, 'utf8').trim();
+        if (orphan) {
+            fs.appendFileSync(legacyDestPath, `\n\n<!-- re-migrated -->\n${orphan}\n`, 'utf8');
+        }
+        fs.rmSync(legacyWorkLogPath);
+    }
+}
+export function ensureWorkspaceScaffold(workspaceRoot, agentName) {
+    fs.mkdirSync(workspaceRoot, { recursive: true });
+    fs.mkdirSync(path.join(workspaceRoot, 'artifacts'), { recursive: true });
+    fs.mkdirSync(path.join(workspaceRoot, 'notes'), { recursive: true });
+    fs.mkdirSync(path.join(workspaceRoot, 'notes', 'channels'), { recursive: true });
+    fs.mkdirSync(path.join(workspaceRoot, 'notes', 'work-log'), { recursive: true });
+    fs.mkdirSync(path.join(workspaceRoot, 'notes', 'archive'), { recursive: true });
+    fs.mkdirSync(path.join(workspaceRoot, 'projects'), { recursive: true });
+    migrateWorkspaceLegacyFiles(workspaceRoot);
+    const taskNotesPath = path.join(workspaceRoot, 'notes', 'tasks.md');
+    if (!fs.existsSync(taskNotesPath)) {
+        fs.writeFileSync(taskNotesPath, [
+            '# Task Notes',
+            '',
+            'Active tasks only (todo / in_progress / in_review). Remove a task here when it is done and archive it.',
+            '',
+        ].join('\n'), 'utf8');
+    }
+    const archiveIndexPath = path.join(workspaceRoot, 'notes', 'archive', 'INDEX.md');
+    if (!fs.existsSync(archiveIndexPath)) {
+        fs.writeFileSync(archiveIndexPath, [
+            '# Archive Index',
+            '',
+            'One line per week: YYYY-Www: <task title> — <one-line result>',
+            '',
+        ].join('\n'), 'utf8');
+    }
+    const currentWeek = getCurrentBeijingISOWeek();
+    const currentWorkLogPath = path.join(workspaceRoot, 'notes', 'work-log', `${currentWeek}.md`);
+    if (!fs.existsSync(currentWorkLogPath)) {
+        fs.writeFileSync(currentWorkLogPath, [
+            `# Work Log ${currentWeek}`,
+            '',
+            'Append key decisions, completed work, and follow-ups for this Beijing week here.',
+            '',
+        ].join('\n'), 'utf8');
+    }
+    const memoryPath = path.join(workspaceRoot, 'MEMORY.md');
+    if (!fs.existsSync(memoryPath)) {
+        fs.writeFileSync(memoryPath, [
+            '# Memory',
+            '',
+            '## Role',
+            buildRoleScaffoldLine(agentName),
+            '',
+            '## Key Knowledge',
+            '- Read `notes/user-preferences.md` for stable user preferences and conventions.',
+            '- Read `notes/channels/<name>.md` for each channel\'s current purpose and active context.',
+            '- Read `notes/tasks.md` for active tasks only (todo / in_progress / in_review).',
+            '- Weekly work log in `notes/work-log/`. Read the current week\'s file for recent decisions; if `notes/work-log/legacy.md` exists, scan it for pre-migration history when older decisions may matter.',
+            '- Completed task archive in `notes/archive/`. Scan `notes/archive/INDEX.md` to locate a specific week.',
+            '- Shared documents, when available, are mounted at `.library/shared`. Before modifying them, read `.library/shared/README.txt`.',
+            '- Keep agent-owned code, scripts, and small projects under `projects/`.',
+            '- Keep generated outputs, exports, logs, screenshots, and other execution results under `artifacts/`.',
+            '- Add topic-specific knowledge under `notes/<topic>.md` as needed.',
+            '',
+            '## Active Context',
+            '- First startup.',
+            '',
+        ].join('\n'), 'utf8');
+    }
+}
+function normalizeRelativePath(relativePath) {
+    return relativePath.replace(/^\/+/, '').trim();
+}
+function toRelativeWorkspacePath(workspaceRoot, absolutePath) {
+    const relative = path.relative(path.resolve(workspaceRoot), path.resolve(absolutePath));
+    return relative === '.' ? '' : relative.split(path.sep).join('/');
+}
+export function getPreviewMimeType(filePath) {
+    const normalized = filePath.toLowerCase();
+    if (normalized.endsWith('.md')
+        || normalized.endsWith('.mdx')
+        || normalized.endsWith('.markdown')
+        || normalized.endsWith('.mdown')
+        || normalized.endsWith('.mkd')) {
+        return 'text/markdown';
+    }
+    if (normalized.endsWith('.png'))
+        return 'image/png';
+    if (normalized.endsWith('.jpg') || normalized.endsWith('.jpeg'))
+        return 'image/jpeg';
+    if (normalized.endsWith('.webp'))
+        return 'image/webp';
+    if (normalized.endsWith('.gif'))
+        return 'image/gif';
+    if (normalized.endsWith('.svg'))
+        return 'image/svg+xml';
+    if (normalized.endsWith('.avif'))
+        return 'image/avif';
+    if (normalized.endsWith('.bmp'))
+        return 'image/bmp';
+    if (normalized.endsWith('.ico'))
+        return 'image/x-icon';
+    return 'text/plain';
+}
+export function looksBinary(content) {
+    const limit = Math.min(content.length, 8_000);
+    for (let index = 0; index < limit; index += 1) {
+        if (content[index] === 0)
+            return true;
+    }
+    return false;
+}