A desktop coding agent with free access to frontier models.
TypeScript
import { createReadStream } from "node:fs";
import { readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { Readable } from "node:stream";
import { recordAudit } from "../audit.js";
import { ApiError } from "../errors.js";
import { FileSessionStore } from "../file-sessions.js";
import type { ApprovalRequest, ServerConfig, TokenScope, WorkspaceInfo } from "../types.js";
import { ensureDir, exists, shortId } from "../utils.js";
import { addRoute, type RequestContext, type Route } from "./registry.js";
/**
* Build a Content-Disposition header value that is safe for Unicode filenames.
* Uses RFC 6266 `filename*` (UTF-8 percent-encoded) with an ASCII fallback.
*/
function contentDisposition(disposition: "attachment" | "inline", filename: string): string {
// ASCII fallback: replace any non-ASCII character with '_'
const asciiName = filename.replace(/[^\x20-\x7E]/g, "_");
const encodedName = encodeURIComponent(filename);
return `${disposition}; filename="${asciiName}"; filename*=UTF-8''${encodedName}`;
}
const FILE_SESSION_DEFAULT_TTL_MS = 15 * 60 * 1000;
const FILE_SESSION_MIN_TTL_MS = 30 * 1000;
const FILE_SESSION_MAX_TTL_MS = 24 * 60 * 60 * 1000;
const FILE_SESSION_MAX_BATCH_ITEMS = 64;
const FILE_SESSION_MAX_FILE_BYTES = 5_000_000;
const FILE_SESSION_CATALOG_DEFAULT_LIMIT = 2000;
const FILE_SESSION_CATALOG_MAX_LIMIT = 10000;
const FILE_BROWSER_EXCLUDED_DIRECTORIES = new Set([".git", "node_modules"]);
const MAX_PATH_COMPONENT_BYTES = 255;
const WINDOWS_RESERVED_PATH_COMPONENT = /^(?:con|prn|aux|nul|clock\$|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?:\..*)?$/i;
type JsonResponse = (data: unknown, status?: number) => Response;
type ReadJsonBody = (request: Request) => Promise<Record<string, unknown>>;
interface RegisterFileRoutesOptions {
routes: Route[];
config: ServerConfig;
jsonResponse: JsonResponse;
readJsonBody: ReadJsonBody;
ensureWritable: (config: ServerConfig) => void;
requireApproval: (ctx: RequestContext, input: Omit<ApprovalRequest, "id" | "createdAt" | "actor">) => Promise<void>;
requireClientScope: (ctx: RequestContext, required: TokenScope) => void;
resolveWorkspace: (config: ServerConfig, id: string) => Promise<WorkspaceInfo>;
resolveInboxEnabled: () => boolean;
resolveOutboxEnabled: () => boolean;
resolveInboxMaxBytes: () => number;
scopeRank: (scope: TokenScope) => number;
}
function resolveInboxDir(workspaceRoot: string): string {
return join(workspaceRoot, ".opencode", "omnirush", "inbox");
}
function resolveOutboxDir(workspaceRoot: string): string {
return join(workspaceRoot, ".opencode", "omnirush", "outbox");
}
export function normalizeWorkspaceRelativePath(input: string, options: { allowSubdirs: boolean }): string {
const inputValue = String(input ?? "");
const hasTrailingSpace = / \s*$/.test(inputValue);
const raw = inputValue.trim();
if (!raw) {
throw new ApiError(400, "invalid_path", "Path is required");
}
if (raw.includes("\u0000")) {
throw new ApiError(400, "invalid_path", "Path contains null byte");
}
if (hasTrailingSpace) {
throw new ApiError(400, "invalid_path", "Path components must not end with a dot or space");
}
// A lot of user-facing surfaces (artifacts, tool logs) reference files as
// `workspace/<path>` or `/workspace/<path>`. The server API expects
// workspace-relative paths, so normalize those common prefixes here.
let normalized = raw.replace(/\\/g, "/");
normalized = normalized.replace(/^\/+/, "");
normalized = normalized.replace(/^\.\//, "");
normalized = normalized.replace(/^workspaces\/[^/]+\//i, "");
normalized = normalized.replace(/^workspace\/(?:ws_[^/]+|\d+|[0-9a-f-]{6,})\//i, "");
normalized = normalized.replace(/^workspace\//, "");
normalized = normalized.replace(/^\/+/, "");
const parts = normalized.split("/").filter(Boolean);
if (!parts.length) {
throw new ApiError(400, "invalid_path", "Path is required");
}
if (!options.allowSubdirs && parts.length > 1) {
throw new ApiError(400, "invalid_path", "Subdirectories are not allowed");
}
for (const part of parts) {
if (part === "." || part === "..") {
throw new ApiError(400, "invalid_path", "Path traversal is not allowed");
}
if (part.includes(":")) {
throw new ApiError(400, "invalid_path", "Path components must not contain colons");
}
if (/[. ]$/.test(part)) {
throw new ApiError(400, "invalid_path", "Path components must not end with a dot or space");
}
if (WINDOWS_RESERVED_PATH_COMPONENT.test(part)) {
throw new ApiError(400, "invalid_path", "Path components must not use Windows reserved device names");
}
if (Buffer.byteLength(part, "utf8") > MAX_PATH_COMPONENT_BYTES) {
throw new ApiError(400, "invalid_path", `Path components must not exceed ${MAX_PATH_COMPONENT_BYTES} UTF-8 bytes`);
}
}
return parts.join("/");
}
async function parseMultipartFormData(request: Request): Promise<FormData> {
try {
return await request.formData();
} catch {
throw new ApiError(400, "invalid_payload", "Malformed multipart/form-data");
}
}
export function isSupportedWorkspaceTextFilePath(relativePath: string): boolean {
const lowered = relativePath.toLowerCase();
return [
".md",
".mdx",
".markdown",
".mmd",
".csv",
".tsv",
".json",
".jsonc",
".yaml",
".yml",
".toml",
".xml",
".html",
".htm",
".ts",
".tsx",
".js",
".jsx",
".mjs",
".cjs",
".css",
".scss",
".astro",
".bash",
".c",
".cc",
".cpp",
".cs",
".dart",
".ex",
".exs",
".go",
".graphql",
".h",
".hpp",
".java",
".kt",
".kts",
".lua",
".php",
".prisma",
".py",
".rb",
".rs",
".sh",
".sql",
".svelte",
".swift",
".vue",
".zig",
".txt",
".log",
].some((ext) =>
lowered.endsWith(ext),
);
}
function resolveSafeChildPath(root: string, child: string): string {
const rootResolved = resolve(root);
const candidate = resolve(rootResolved, child);
if (candidate === rootResolved) {
throw new ApiError(400, "invalid_path", "Path must point to a file");
}
if (!candidate.startsWith(rootResolved + sep)) {
throw new ApiError(400, "invalid_path", "Path traversal is not allowed");
}
return candidate;
}
function encodeArtifactId(path: string): string {
return Buffer.from(path, "utf8").toString("base64url");
}
function decodeArtifactId(id: string): string {
const raw = (id ?? "").trim();
if (!raw) {
throw new ApiError(400, "invalid_artifact", "Artifact id is required");
}
try {
const decoded = Buffer.from(raw, "base64url").toString("utf8");
return normalizeWorkspaceRelativePath(decoded, { allowSubdirs: true });
} catch {
throw new ApiError(400, "invalid_artifact", "Artifact id is invalid");
}
}
function contentTypeForPath(path: string): string {
const lowered = path.toLowerCase();
if (lowered.endsWith(".html") || lowered.endsWith(".htm")) return "text/html; charset=utf-8";
if (lowered.endsWith(".svg")) return "image/svg+xml";
if (lowered.endsWith(".png")) return "image/png";
if (lowered.endsWith(".jpg") || lowered.endsWith(".jpeg")) return "image/jpeg";
if (lowered.endsWith(".gif")) return "image/gif";
if (lowered.endsWith(".webp")) return "image/webp";
if (lowered.endsWith(".pdf")) return "application/pdf";
if (lowered.endsWith(".docx")) return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
if (lowered.endsWith(".csv")) return "text/csv; charset=utf-8";
if (lowered.endsWith(".tsv")) return "text/tab-separated-values; charset=utf-8";
if (lowered.endsWith(".xlsx")) return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
if (lowered.endsWith(".xls")) return "application/vnd.ms-excel";
if (lowered.endsWith(".ods")) return "application/vnd.oasis.opendocument.spreadsheet";
if (lowered.endsWith(".pptx")) return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
if (lowered.endsWith(".ppt")) return "application/vnd.ms-powerpoint";
if (lowered.endsWith(".pptm")) return "application/vnd.ms-powerpoint.presentation.macroEnabled.12";
if (lowered.endsWith(".potx")) return "application/vnd.openxmlformats-officedocument.presentationml.template";
if (lowered.endsWith(".pot")) return "application/vnd.ms-powerpoint";
if (lowered.endsWith(".odp")) return "application/vnd.oasis.opendocument.presentation";
if (isSupportedWorkspaceTextFilePath(path)) return "text/plain; charset=utf-8";
return "application/octet-stream";
}
type ArtifactTargetInput = {
kind?: unknown;
value?: unknown;
name?: unknown;
preview?: unknown;
confidence?: unknown;
reason?: unknown;
};
function artifactPreviewForPath(path: string): string {
const lowered = path.toLowerCase();
if (/\.(md|markdown|mdx|mmd)$/.test(lowered)) return "markdown";
if (/\.(csv|tsv|xlsx|xls|ods)$/.test(lowered)) return "sheet";
if (/\.(ppt|pptx|pptm|pot|potx|odp|key|sxi)$/.test(lowered)) return "slides";
if (lowered.endsWith(".docx")) return "document";
if (/\.(png|jpe?g|gif|webp|svg)$/.test(lowered)) return "image";
if (lowered.endsWith(".pdf")) return "pdf";
if (/\.(html|htm)$/.test(lowered)) return "html";
if (/\.(astro|bash|c|cc|cpp|cs|css|dart|ex|exs|go|graphql|h|hpp|java|js|jsx|json|jsonc|kt|kts|lua|mjs|cjs|php|prisma|py|rb|rs|scss|sh|sql|svelte|swift|toml|ts|tsx|vue|xml|yaml|yml|zig)$/.test(lowered)) return "code";
if (isSupportedWorkspaceTextFilePath(path)) return "text";
return "external";
}
function normalizeUrlTarget(value: string): string | null {
try {
const url = new URL(value.trim());
if (!["http:", "https:", "ws:", "wss:"].includes(url.protocol)) return null;
return url.toString();
} catch {
return null;
}
}
export async function resolveWorkspaceArtifactTargets(workspaceRoot: string, input: unknown): Promise<Array<Record<string, unknown>>> {
const targets = Array.isArray(input) ? input.slice(0, 80) : [];
const results = new Map<string, Record<string, unknown>>();
const workspaceResolved = resolve(workspaceRoot);
for (const item of targets) {
if (!item || typeof item !== "object") continue;
const target = item as ArtifactTargetInput;
const kind = target.kind === "url" ? "url" : "file";
const rawValue = typeof target.value === "string" ? target.value.trimStart() : "";
if (!rawValue.trim()) continue;
const confidence = typeof target.confidence === "number" && Number.isFinite(target.confidence) ? target.confidence : 0;
const reason = typeof target.reason === "string" ? target.reason : "server";
if (kind === "url") {
const url = normalizeUrlTarget(rawValue);
if (!url) continue;
const key = `url:${url}`;
const next = {
id: key,
kind: "url",
value: url,
name: typeof target.name === "string" && target.name.trim() ? target.name.trim() : url,
preview: "browser",
confidence,
reason,
exists: true,
};
const previous = results.get(key);
if (!previous || confidence >= Number(previous.confidence ?? 0)) results.set(key, next);
continue;
}
let relativePath: string;
try {
if (isAbsolute(rawValue)) {
const absolutePath = resolve(rawValue);
const pathFromWorkspace = relative(workspaceResolved, absolutePath);
if (!pathFromWorkspace || pathFromWorkspace === ".." || pathFromWorkspace.startsWith(`..${sep}`) || isAbsolute(pathFromWorkspace)) {
continue;
}
relativePath = normalizeWorkspaceRelativePath(pathFromWorkspace, { allowSubdirs: true });
} else {
relativePath = normalizeWorkspaceRelativePath(rawValue, { allowSubdirs: true });
}
} catch {
continue;
}
const key = `file:${relativePath.toLowerCase()}`;
const absPath = resolveSafeChildPath(workspaceRoot, relativePath);
let existsFile = false;
let size: number | undefined;
let updatedAt: number | undefined;
let kindValue: "file" | "dir" | "other" | undefined;
if (await exists(absPath)) {
const info = await stat(absPath);
kindValue = info.isFile() ? "file" : info.isDirectory() ? "dir" : "other";
existsFile = info.isFile();
size = info.size;
updatedAt = info.mtimeMs;
}
const next = {
id: key,
kind: "file",
value: relativePath,
name: basename(relativePath),
preview: artifactPreviewForPath(relativePath),
confidence,
reason,
exists: existsFile,
fileKind: kindValue,
size,
updatedAt,
contentType: contentTypeForPath(relativePath),
};
const previous = results.get(key);
if (!previous || confidence >= Number(previous.confidence ?? 0)) results.set(key, next);
}
return Array.from(results.values());
}
function encodeInboxId(path: string): string {
return encodeArtifactId(path);
}
function decodeInboxId(id: string): string {
try {
return decodeArtifactId(id);
} catch {
throw new ApiError(400, "invalid_inbox_item", "Inbox item id is invalid");
}
}
async function listArtifacts(outboxRoot: string): Promise<Array<{ id: string; path: string; size: number; updatedAt: number }>> {
const rootResolved = resolve(outboxRoot);
if (!(await exists(rootResolved))) return [];
const items: Array<{ id: string; path: string; size: number; updatedAt: number }> = [];
const walk = async (dir: string) => {
const entries = await readdir(dir, { withFileTypes: true });
for (const entry of entries) {
const abs = join(dir, entry.name);
if (entry.isDirectory()) {
await walk(abs);
continue;
}
if (!entry.isFile()) continue;
const rel = normalizeWorkspaceRelativePath(relative(rootResolved, abs), { allowSubdirs: true });
const info = await stat(abs);
items.push({
id: encodeArtifactId(rel),
path: rel,
size: info.size,
updatedAt: info.mtimeMs,
});
}
};
try {
await walk(rootResolved);
} catch {
return [];
}
items.sort((a, b) => b.updatedAt - a.updatedAt);
return items;
}
async function listInbox(inboxRoot: string): Promise<Array<{ id: string; path: string; size: number; updatedAt: number; name: string }>> {
const items = await listArtifacts(inboxRoot);
return items.map((item) => ({
...item,
id: encodeInboxId(item.path),
name: basename(item.path),
}));
}
type FileSessionCatalogEntry = {
path: string;
kind: "file" | "dir";
size: number;
mtimeMs: number;
revision: string;
};
function fileRevision(info: { mtimeMs: number; size: number }): string {
return `${Math.floor(info.mtimeMs)}:${info.size}`;
}
function parseFileSessionTtlMs(input: unknown): number {
const raw = typeof input === "number" && Number.isFinite(input) ? input : Number.NaN;
if (Number.isNaN(raw)) return FILE_SESSION_DEFAULT_TTL_MS;
const ttlMs = Math.floor(raw * 1000);
if (ttlMs < FILE_SESSION_MIN_TTL_MS) return FILE_SESSION_MIN_TTL_MS;
if (ttlMs > FILE_SESSION_MAX_TTL_MS) return FILE_SESSION_MAX_TTL_MS;
return ttlMs;
}
function parseCatalogLimit(input: string | null): number {
if (!input) return FILE_SESSION_CATALOG_DEFAULT_LIMIT;
const parsed = Number(input);
if (!Number.isFinite(parsed) || parsed <= 0) return FILE_SESSION_CATALOG_DEFAULT_LIMIT;
return Math.min(Math.floor(parsed), FILE_SESSION_CATALOG_MAX_LIMIT);
}
function parseCatalogPathFilter(input: string | null): string | null {
if (!input) return null;
if (!input.trim()) return null;
return normalizeWorkspaceRelativePath(input, { allowSubdirs: true });
}
function matchesCatalogFilter(path: string, filter: string | null): boolean {
if (!filter) return true;
return path === filter || path.startsWith(`${filter}/`);
}
function normalizeResolvedRelativePath(input: string): string {
const normalized = input.replace(/\\/g, "/");
const parts = normalized.split("/").filter(Boolean);
if (!parts.length) {
throw new ApiError(400, "invalid_path", "Path is required");
}
for (const part of parts) {
if (part === "." || part === "..") {
throw new ApiError(400, "invalid_path", "Path traversal is not allowed");
}
}
return parts.join("/");
}
async function listWorkspaceCatalogEntries(workspaceRoot: string, excludeHeavyDirectories = false) {
const rootResolved = resolve(workspaceRoot);
const items: FileSessionCatalogEntry[] = [];
const skippedDirectories: string[] = [];
const walk = async (dirPath: string) => {
const entries = await readdir(dirPath, { withFileTypes: true }).catch((error: unknown) => {
if (error instanceof Error && "code" in error && (error.code === "EACCES" || error.code === "EPERM")) {
if (dirPath === rootResolved) {
throw new ApiError(403, "workspace_permission_denied", "OmniRush.ai does not have permission to list this workspace folder.");
}
skippedDirectories.push(relative(rootResolved, dirPath).replace(/\\/g, "/"));
return [];
}
if (dirPath === rootResolved && error instanceof Error && "code" in error && error.code === "ENOENT") {
throw new ApiError(404, "workspace_not_found", "The workspace folder no longer exists.");
}
throw error;
});
entries.sort((a, b) => a.name.localeCompare(b.name));
for (const entry of entries) {
if (excludeHeavyDirectories && entry.isDirectory() && FILE_BROWSER_EXCLUDED_DIRECTORIES.has(entry.name)) {
continue;
}
const absPath = join(dirPath, entry.name);
const relRaw = relative(rootResolved, absPath).replace(/\\/g, "/");
const rel = normalizeResolvedRelativePath(relRaw);
if (entry.isDirectory()) {
const info = await stat(absPath);
items.push({
path: rel,
kind: "dir",
size: 0,
mtimeMs: info.mtimeMs,
revision: fileRevision({ mtimeMs: info.mtimeMs, size: 0 }),
});
await walk(absPath);
continue;
}
if (!entry.isFile()) continue;
const info = await stat(absPath);
items.push({
path: rel,
kind: "file",
size: info.size,
mtimeMs: info.mtimeMs,
revision: fileRevision(info),
});
}
};
await walk(rootResolved);
items.sort((a, b) => a.path.localeCompare(b.path));
return { items, skippedDirectories };
}
export function registerFileRoutes(options: RegisterFileRoutesOptions): void {
const {
routes,
config,
jsonResponse,
readJsonBody,
ensureWritable,
requireApproval,
requireClientScope,
resolveWorkspace,
resolveInboxEnabled,
resolveOutboxEnabled,
resolveInboxMaxBytes,
scopeRank,
} = options;
const fileSessions = new FileSessionStore();
const serializeFileSession = (session: {
id: string;
workspaceId: string;
createdAt: number;
expiresAt: number;
canWrite: boolean;
}) => ({
id: session.id,
workspaceId: session.workspaceId,
createdAt: session.createdAt,
expiresAt: session.expiresAt,
ttlMs: Math.max(0, session.expiresAt - Date.now()),
canWrite: session.canWrite,
});
const resolveFileSession = (ctx: RequestContext, sessionId: string) => {
const session = fileSessions.get(sessionId);
if (!session) {
throw new ApiError(404, "file_session_not_found", "File session not found");
}
if (!ctx.actor?.tokenHash || session.actorTokenHash !== ctx.actor.tokenHash) {
throw new ApiError(403, "forbidden", "File session does not belong to this token");
}
const workspace = config.workspaces.find((item) => item.id === session.workspaceId);
if (!workspace) {
throw new ApiError(404, "workspace_not_found", "Workspace not found for this file session");
}
return { session, workspace };
};
const recordWorkspaceFileEvent = (workspaceId: string, input: { type: "write" | "delete" | "rename" | "mkdir"; path: string; toPath?: string; revision?: string }) => {
return fileSessions.recordWorkspaceEvent({ workspaceId, ...input });
};
addRoute(routes, "GET", "/workspace/:id/inbox", "client", async (ctx) => {
const workspace = await resolveWorkspace(config, ctx.params.id);
if (!resolveInboxEnabled()) {
return jsonResponse({ items: [] });
}
const inboxRoot = resolveInboxDir(workspace.path);
const items = await listInbox(inboxRoot);
return jsonResponse({ items });
});
addRoute(routes, "GET", "/workspace/:id/inbox/:inboxId", "client", async (ctx) => {
const workspace = await resolveWorkspace(config, ctx.params.id);
if (!resolveInboxEnabled()) {
throw new ApiError(404, "inbox_disabled", "Workspace inbox is disabled");
}
const inboxRoot = resolveInboxDir(workspace.path);
const relativePath = decodeInboxId(ctx.params.inboxId);
const absPath = resolveSafeChildPath(inboxRoot, relativePath);
if (!(await exists(absPath))) {
throw new ApiError(404, "inbox_item_not_found", "Inbox item not found");
}
const info = await stat(absPath);
if (!info.isFile()) {
throw new ApiError(404, "inbox_item_not_found", "Inbox item not found");
}
const headers = new Headers();
headers.set("Content-Type", "application/octet-stream");
headers.set("Content-Length", String(info.size));
headers.set("Content-Disposition", contentDisposition("attachment", basename(relativePath)));
const stream = Readable.toWeb(createReadStream(absPath)) as unknown as ReadableStream;
return new Response(stream, { status: 200, headers });
});
addRoute(routes, "POST", "/workspace/:id/inbox", "client", async (ctx) => {
ensureWritable(config);
requireClientScope(ctx, "collaborator");
if (!resolveInboxEnabled()) {
throw new ApiError(404, "inbox_disabled", "Workspace inbox is disabled");
}
const workspace = await resolveWorkspace(config, ctx.params.id);
const contentType = ctx.request.headers.get("content-type") ?? "";
if (!contentType.toLowerCase().includes("multipart/form-data")) {
throw new ApiError(400, "invalid_payload", "Expected multipart/form-data");
}
const form = await parseMultipartFormData(ctx.request);
const file = form.get("file");
if (!(file instanceof File)) {
throw new ApiError(400, "file_required", "Form field 'file' is required");
}
const queryPath = ctx.url.searchParams.get("path") ?? "";
const formPath = typeof form.get("path") === "string" ? String(form.get("path") || "") : "";
const requestedPath = queryPath.trim() ? queryPath : formPath.trim() ? formPath : file.name;
const relativePath = normalizeWorkspaceRelativePath(requestedPath, { allowSubdirs: true });
const inboxRoot = resolveInboxDir(workspace.path);
const dest = resolveSafeChildPath(inboxRoot, relativePath);
const maxBytes = resolveInboxMaxBytes();
if (file.size > maxBytes) {
throw new ApiError(413, "file_too_large", "File exceeds upload limit", { maxBytes, size: file.size });
}
// Inbox uploads are exempt from host approval: the inbox is the designated
// client drop area (path-constrained via resolveSafeChildPath, size-capped,
// audited, and disable-able via inbox.enabled). Parking the upload on the
// manual-approval queue froze web/gateway clients for the whole approval
// timeout and then failed the send, because client tokens cannot approve
// their own writes. All other write routes remain approval-gated.
await ensureDir(dirname(dest));
const bytes = Buffer.from(await file.arrayBuffer());
const tmp = join(dirname(dest), `.upload-${shortId()}.tmp`);
await writeFile(tmp, bytes);
await rename(tmp, dest);
await recordAudit(workspace.path, {
id: shortId(),
workspaceId: workspace.id,
actor: ctx.actor ?? { type: "remote" },
action: "workspace.inbox.upload",
target: dest,
summary: `Uploaded ${relativePath} to inbox`,
timestamp: Date.now(),
});
return jsonResponse({ ok: true, path: relativePath, bytes: file.size });
});
addRoute(routes, "GET", "/workspace/:id/artifacts", "client", async (ctx) => {
const workspace = await resolveWorkspace(config, ctx.params.id);
if (!resolveOutboxEnabled()) {
return jsonResponse({ items: [] });
}
const outboxRoot = resolveOutboxDir(workspace.path);
const items = await listArtifacts(outboxRoot);
return jsonResponse({ items });
});
addRoute(routes, "GET", "/workspace/:id/artifacts/:artifactId", "client", async (ctx) => {
const workspace = await resolveWorkspace(config, ctx.params.id);
if (!resolveOutboxEnabled()) {
throw new ApiError(404, "outbox_disabled", "Workspace outbox is disabled");
}
const outboxRoot = resolveOutboxDir(workspace.path);
const relativePath = decodeArtifactId(ctx.params.artifactId);
const absPath = resolveSafeChildPath(outboxRoot, relativePath);
if (!(await exists(absPath))) {
throw new ApiError(404, "artifact_not_found", "Artifact not found");
}
const info = await stat(absPath);
if (!info.isFile()) {
throw new ApiError(404, "artifact_not_found", "Artifact not found");
}
const headers = new Headers();
headers.set("Content-Type", "application/octet-stream");
headers.set("Content-Length", String(info.size));
headers.set("Content-Disposition", contentDisposition("attachment", basename(relativePath)));
const stream = Readable.toWeb(createReadStream(absPath)) as unknown as ReadableStream;
return new Response(stream, { status: 200, headers });
});
addRoute(routes, "POST", "/workspace/:id/artifacts/resolve", "client", async (ctx) => {
const workspace = await resolveWorkspace(config, ctx.params.id);
const body = await readJsonBody(ctx.request);
const items = await resolveWorkspaceArtifactTargets(workspace.path, body.targets);
return jsonResponse({ items });
});
addRoute(routes, "POST", "/workspace/:id/files/sessions", "client", async (ctx) => {
const workspace = await resolveWorkspace(config, ctx.params.id);
const body = await readJsonBody(ctx.request);
const ttlMs = parseFileSessionTtlMs(body.ttlSeconds);
const requestWrite = body.write !== false;
const canWrite =
requestWrite &&
!config.readOnly &&
scopeRank(ctx.actor?.scope ?? "viewer") >= scopeRank("collaborator");
const session = fileSessions.create({
workspaceId: workspace.id,
workspaceRoot: workspace.path,
actorTokenHash: ctx.actor?.tokenHash ?? "",
actorScope: ctx.actor?.scope ?? "viewer",
canWrite,
ttlMs,
});
return jsonResponse({ session: serializeFileSession(session) });
});
addRoute(routes, "DELETE", "/files/sessions/:sessionId", "client", async (ctx) => {
const { session } = resolveFileSession(ctx, ctx.params.sessionId);
fileSessions.close(session.id);
return jsonResponse({ ok: true });
});
addRoute(routes, "GET", "/files/sessions/:sessionId/catalog/snapshot", "client", async (ctx) => {
const { workspace } = resolveFileSession(ctx, ctx.params.sessionId);
const prefix = parseCatalogPathFilter(ctx.url.searchParams.get("prefix"));
const after = parseCatalogPathFilter(ctx.url.searchParams.get("after"));
const includeDirs = ctx.url.searchParams.get("includeDirs") !== "false";
const limit = parseCatalogLimit(ctx.url.searchParams.get("limit"));
const excludeHeavyDirectories = ctx.url.searchParams.get("excludeHeavyDirectories") === "true";
const { items: entries, skippedDirectories } = await listWorkspaceCatalogEntries(workspace.path, excludeHeavyDirectories);
const filtered = entries.filter((entry) => {
if (!includeDirs && entry.kind === "dir") return false;
if (!matchesCatalogFilter(entry.path, prefix)) return false;
if (after && entry.path <= after) return false;
return true;
});
const items = filtered.slice(0, limit);
const truncated = filtered.length > items.length;
const nextAfter = truncated ? items[items.length - 1]?.path : undefined;
const events = fileSessions.listWorkspaceEvents(workspace.id, Number.MAX_SAFE_INTEGER);
return jsonResponse({
sessionId: ctx.params.sessionId,
workspaceId: workspace.id,
generatedAt: Date.now(),
cursor: events.cursor,
total: filtered.length,
incomplete: skippedDirectories.length > 0,
skippedDirectories,
truncated,
nextAfter,
items,
});
});
addRoute(routes, "POST", "/files/sessions/:sessionId/ops", "client", async (ctx) => {
ensureWritable(config);
requireClientScope(ctx, "collaborator");
const { session, workspace } = resolveFileSession(ctx, ctx.params.sessionId);
if (!session.canWrite) {
throw new ApiError(403, "forbidden", "File session is read-only");
}
const body = await readJsonBody(ctx.request);
const operations = Array.isArray(body.operations)
? (body.operations as Array<Record<string, unknown>>)
: null;
if (!operations || !operations.length) {
throw new ApiError(400, "invalid_payload", "operations must be a non-empty array");
}
if (operations.length > FILE_SESSION_MAX_BATCH_ITEMS) {
throw new ApiError(400, "invalid_payload", `operations must include <= ${FILE_SESSION_MAX_BATCH_ITEMS} items`);
}
const items: Array<Record<string, unknown>> = [];
const approvalPaths: string[] = [];
for (const op of operations) {
if (typeof op?.path === "string" && op.path.trim()) {
approvalPaths.push(resolveSafeChildPath(workspace.path, normalizeWorkspaceRelativePath(op.path, { allowSubdirs: true })));
}
if (typeof op?.from === "string" && op.from.trim()) {
approvalPaths.push(resolveSafeChildPath(workspace.path, normalizeWorkspaceRelativePath(op.from, { allowSubdirs: true })));
}
if (typeof op?.to === "string" && op.to.trim()) {
approvalPaths.push(resolveSafeChildPath(workspace.path, normalizeWorkspaceRelativePath(op.to, { allowSubdirs: true })));
}
}
if (approvalPaths.length) {
await requireApproval(ctx, {
workspaceId: workspace.id,
action: "workspace.files.session.ops",
summary: `Apply ${operations.length} file operation(s) via file session`,
paths: approvalPaths,
});
}
for (const op of operations) {
const type = String(op.type ?? "").trim();
try {
if (type === "mkdir") {
const path = normalizeWorkspaceRelativePath(String(op.path ?? ""), { allowSubdirs: true });
const absPath = resolveSafeChildPath(workspace.path, path);
await ensureDir(absPath);
recordWorkspaceFileEvent(workspace.id, { type: "mkdir", path });
items.push({ ok: true, type, path });
continue;
}
if (type === "delete") {
const path = normalizeWorkspaceRelativePath(String(op.path ?? ""), { allowSubdirs: true });
const absPath = resolveSafeChildPath(workspace.path, path);
if (!(await exists(absPath))) {
items.push({ ok: false, type, path, code: "file_not_found", message: "Path not found" });
continue;
}
await rm(absPath, { recursive: op.recursive === true, force: false });
recordWorkspaceFileEvent(workspace.id, { type: "delete", path });
items.push({ ok: true, type, path });
continue;
}
if (type === "rename") {
const from = normalizeWorkspaceRelativePath(String(op.from ?? ""), { allowSubdirs: true });
const to = normalizeWorkspaceRelativePath(String(op.to ?? ""), { allowSubdirs: true });
const fromAbs = resolveSafeChildPath(workspace.path, from);
const toAbs = resolveSafeChildPath(workspace.path, to);
if (!(await exists(fromAbs))) {
items.push({ ok: false, type, from, to, code: "file_not_found", message: "Source path not found" });
continue;
}
await ensureDir(dirname(toAbs));
await rename(fromAbs, toAbs);
recordWorkspaceFileEvent(workspace.id, { type: "rename", path: from, toPath: to });
items.push({ ok: true, type, from, to });
continue;
}
items.push({ ok: false, type, code: "invalid_operation", message: `Unsupported operation type: ${type}` });
} catch (error) {
const message = error instanceof Error ? error.message : "Operation failed";
items.push({ ok: false, type, code: "operation_failed", message });
}
}
const events = fileSessions.listWorkspaceEvents(workspace.id, Number.MAX_SAFE_INTEGER);
return jsonResponse({ items, cursor: events.cursor });
});
addRoute(routes, "GET", "/workspace/:id/files/content", "client", async (ctx) => {
const workspace = await resolveWorkspace(config, ctx.params.id);
const requested = ctx.url.searchParams.get("path") ?? "";
const relativePath = normalizeWorkspaceRelativePath(requested, { allowSubdirs: true });
if (!isSupportedWorkspaceTextFilePath(relativePath)) {
throw new ApiError(400, "invalid_path", "Only supported text artifact files can be read inline");
}
const absPath = resolveSafeChildPath(workspace.path, relativePath);
if (!(await exists(absPath))) {
throw new ApiError(404, "file_not_found", "File not found");
}
const info = await stat(absPath);
if (!info.isFile()) {
throw new ApiError(404, "file_not_found", "File not found");
}
const maxBytes = FILE_SESSION_MAX_FILE_BYTES;
if (info.size > maxBytes) {
throw new ApiError(413, "file_too_large", "File exceeds size limit", { maxBytes, size: info.size });
}
const content = await readFile(absPath, "utf8");
return jsonResponse({ path: relativePath, content, bytes: info.size, updatedAt: info.mtimeMs });
});
addRoute(routes, "GET", "/workspace/:id/files/stat", "client", async (ctx) => {
const workspace = await resolveWorkspace(config, ctx.params.id);
const requested = ctx.url.searchParams.get("path") ?? "";
const relativePath = normalizeWorkspaceRelativePath(requested, { allowSubdirs: true });
const absPath = resolveSafeChildPath(workspace.path, relativePath);
if (!(await exists(absPath))) {
return jsonResponse({ ok: true, path: relativePath, exists: false });
}
const info = await stat(absPath);
return jsonResponse({
ok: true,
path: relativePath,
exists: true,
kind: info.isFile() ? "file" : info.isDirectory() ? "dir" : "other",
size: info.size,
updatedAt: info.mtimeMs,
});
});
addRoute(routes, "GET", "/workspace/:id/files/raw", "client", async (ctx) => {
const workspace = await resolveWorkspace(config, ctx.params.id);
const requested = ctx.url.searchParams.get("path") ?? "";
const relativePath = normalizeWorkspaceRelativePath(requested, { allowSubdirs: true });
const absPath = resolveSafeChildPath(workspace.path, relativePath);
if (!(await exists(absPath))) {
throw new ApiError(404, "file_not_found", "File not found");
}
const info = await stat(absPath);
if (!info.isFile()) {
throw new ApiError(404, "file_not_found", "File not found");
}
const headers = new Headers();
headers.set("Content-Type", contentTypeForPath(relativePath));
headers.set("Content-Length", String(info.size));
headers.set("Content-Disposition", contentDisposition("inline", basename(relativePath)));
const stream = Readable.toWeb(createReadStream(absPath)) as unknown as ReadableStream;
return new Response(stream, { status: 200, headers });
});
addRoute(routes, "POST", "/workspace/:id/files/raw", "client", async (ctx) => {
ensureWritable(config);
requireClientScope(ctx, "collaborator");
const workspace = await resolveWorkspace(config, ctx.params.id);
const body = await readJsonBody(ctx.request);
const requestedPath = String(body.path ?? "");
const relativePath = normalizeWorkspaceRelativePath(requestedPath, { allowSubdirs: true });
if (typeof body.dataBase64 !== "string") {
throw new ApiError(400, "invalid_payload", "dataBase64 must be a string");
}
let bytes: Buffer;
try {
bytes = Buffer.from(body.dataBase64, "base64");
} catch {
throw new ApiError(400, "invalid_payload", "dataBase64 is invalid");
}
const maxBytes = FILE_SESSION_MAX_FILE_BYTES;
if (bytes.byteLength > maxBytes) {
throw new ApiError(413, "file_too_large", "File exceeds size limit", { maxBytes, size: bytes.byteLength });
}
const baseUpdatedAtRaw = body.baseUpdatedAt;
const baseUpdatedAt =
typeof baseUpdatedAtRaw === "number" && Number.isFinite(baseUpdatedAtRaw) ? baseUpdatedAtRaw : null;
const force = body.force === true;
const absPath = resolveSafeChildPath(workspace.path, relativePath);
const before = (await exists(absPath)) ? await stat(absPath) : null;
if (before && !before.isFile()) {
throw new ApiError(400, "invalid_path", "Path must point to a file");
}
const beforeUpdatedAt = before ? before.mtimeMs : null;
if (!force && beforeUpdatedAt !== null && baseUpdatedAt !== null && beforeUpdatedAt !== baseUpdatedAt) {
throw new ApiError(409, "conflict", "File changed since it was loaded", { baseUpdatedAt, currentUpdatedAt: beforeUpdatedAt });
}
await requireApproval(ctx, {
workspaceId: workspace.id,
action: "workspace.file.write",
summary: `Write ${relativePath}`,
paths: [absPath],
});
await ensureDir(dirname(absPath));
const tmp = `${absPath}.tmp-${shortId()}`;
await writeFile(tmp, bytes);
await rename(tmp, absPath);
const after = await stat(absPath);
const revision = fileRevision(after);
recordWorkspaceFileEvent(workspace.id, { type: "write", path: relativePath, revision });
await recordAudit(workspace.path, {
id: shortId(),
workspaceId: workspace.id,
actor: ctx.actor ?? { type: "remote" },
action: "workspace.file.write",
target: absPath,
summary: `Wrote ${relativePath}`,
timestamp: Date.now(),
});
return jsonResponse({ ok: true, path: relativePath, bytes: bytes.byteLength, updatedAt: after.mtimeMs, revision });
});
addRoute(routes, "POST", "/workspace/:id/files/content", "client", async (ctx) => {
ensureWritable(config);
requireClientScope(ctx, "collaborator");
const workspace = await resolveWorkspace(config, ctx.params.id);
const body = await readJsonBody(ctx.request);
const requestedPath = String(body.path ?? "");
const relativePath = normalizeWorkspaceRelativePath(requestedPath, { allowSubdirs: true });
if (!isSupportedWorkspaceTextFilePath(relativePath)) {
throw new ApiError(400, "invalid_path", "Only supported text artifact files can be edited inline");
}
if (typeof body.content !== "string") {
throw new ApiError(400, "invalid_payload", "content must be a string");
}
const content = body.content;
const bytes = Buffer.byteLength(content, "utf8");
const maxBytes = FILE_SESSION_MAX_FILE_BYTES;
if (bytes > maxBytes) {
throw new ApiError(413, "file_too_large", "File exceeds size limit", { maxBytes, size: bytes });
}
const baseUpdatedAtRaw = body.baseUpdatedAt;
const baseUpdatedAt =
typeof baseUpdatedAtRaw === "number" && Number.isFinite(baseUpdatedAtRaw) ? baseUpdatedAtRaw : null;
const force = body.force === true;
const absPath = resolveSafeChildPath(workspace.path, relativePath);
const before = (await exists(absPath)) ? await stat(absPath) : null;
if (before && !before.isFile()) {
throw new ApiError(400, "invalid_path", "Path must point to a file");
}
const beforeUpdatedAt = before ? before.mtimeMs : null;
if (!force && beforeUpdatedAt !== null && baseUpdatedAt !== null && beforeUpdatedAt !== baseUpdatedAt) {
throw new ApiError(409, "conflict", "File changed since it was loaded", {
baseUpdatedAt,
currentUpdatedAt: beforeUpdatedAt,
});
}
await requireApproval(ctx, {
workspaceId: workspace.id,
action: "workspace.file.write",
summary: `Write ${relativePath}`,
paths: [absPath],
});
await ensureDir(dirname(absPath));
const tmp = `${absPath}.tmp-${shortId()}`;
await writeFile(tmp, content, "utf8");
await rename(tmp, absPath);
const after = await stat(absPath);
const revision = fileRevision(after);
recordWorkspaceFileEvent(workspace.id, {
type: "write",
path: relativePath,
revision,
});
await recordAudit(workspace.path, {
id: shortId(),
workspaceId: workspace.id,
actor: ctx.actor ?? { type: "remote" },
action: "workspace.file.write",
target: absPath,
summary: `Wrote ${relativePath}`,
timestamp: Date.now(),
});
return jsonResponse({ ok: true, path: relativePath, bytes, updatedAt: after.mtimeMs, revision });
});
}