@deepseek-ai/dsh-api-workspace-files 0.1.5-alpha.1 → 0.1.5-alpha.2

package/lib/index.js

@@ -1,3 +1,4 @@
+import { posix, win32 } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { Remote, RemoteError, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { Deque } from "@deepseek-ai/dsh-deque";
@@ -5,8 +6,8 @@ import { Deque } from "@deepseek-ai/dsh-deque";
 /**
 * Producer of the `changes` stream: every `fs/observed` emission whose target
 * lies inside a generation's workspace root becomes one frame of that
-* generation. Observations are emitted by tools after their own filesystem
-* operation, so the feed covers Agent writes only; the OS is not watched.
+* generation. Instrumented filesystem operations emit these observations; the
+* operating system is not watched.
 * Each generation acknowledges its observation queue and resolved workspace
 * root with `ready` before emitting any queued or live changes.
 */
@@ -107,22 +108,16 @@ var ChangeFollower = class {
 //#endregion
 //#region lib/types/index.js
 /**
-* Workspace file service: paged text reads, byte-window reads, stats, directory
-* listings, and the agent-write change feed inside one session's workspace
-* root, exposed as the `workspaceFiles` Remote namespace.
+* Workspace file service: read-only file previews, workspace directory
+* listings, and the filesystem-observation change feed, exposed as
+* `workspaceFiles`.
 *
-* Reads through `ctx.fs` are deliberately unconfined — the sandboxing backend
-* fences writes and edits only, and says so. Every constraint this service
-* needs is therefore its own, and there are four:
-*
-* 1. The path is authorized by containment in the session's workspace root.
-* 2. Containment is decided by {@link FileSystem.contains}, never by comparing
-*    path strings: `resolve` realpaths, so a prefix test cannot see a symlink
-*    that leaves the root. `lstat` rejects a link before that follow happens.
-* 3. Every cap is validated Config, changeable per deployment. A page is cut by
-*    lines and refused, not shortened, when its bytes exceed the byte cap; a
-*    listing is cut by entries and says so.
-* 4. Failures are one `RemoteError` per reason, declared in `./types`.
+* File reads follow the composed filesystem's read access, including paths
+* outside the workspace. The selected Session header supplies the base for
+* relative paths, with the sandbox policy root as its no-cwd fallback, not a
+* read-containment restriction. Directory listings and change observations
+* remain workspace-scoped. File-kind checks and configured read caps apply to
+* every preview; this service exposes no mutations.
 *
 * A page is cut from `streamText`, which decodes and rejects non-UTF-8 as it
 * goes, so the file is read only up to the first character past the page and
@@ -247,12 +242,14 @@ function directoryEntry(child) {
 		...child.size === void 0 ? {} : { size: child.size }
 	};
 }
-/** Host Remote service over the composed filesystem, confined to one workspace. */
+/** Host Remote file reads and workspace directory observations over the composed filesystem. */
 let WorkspaceFiles = (() => {
 	let _classSuper = TypertRemoteService;
 	let _instanceExtraInitializers = [];
 	let _read_decorators;
 	let _readBytes_decorators;
+	let _readAll_decorators;
+	let _readRelated_decorators;
 	let _stat_decorators;
 	let _list_decorators;
 	let _changes_decorators;
@@ -261,6 +258,8 @@ let WorkspaceFiles = (() => {
 			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
 			_read_decorators = [Remote];
 			_readBytes_decorators = [Remote];
+			_readAll_decorators = [Remote];
+			_readRelated_decorators = [Remote];
 			_stat_decorators = [Remote];
 			_list_decorators = [Remote];
 			_changes_decorators = [Remote({ mode: "stream" })];
@@ -286,6 +285,28 @@ let WorkspaceFiles = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _readAll_decorators, {
+				kind: "method",
+				name: "readAll",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "readAll" in obj,
+					get: (obj) => obj.readAll
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _readRelated_decorators, {
+				kind: "method",
+				name: "readRelated",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "readRelated" in obj,
+					get: (obj) => obj.readRelated
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			__esDecorate(this, null, _stat_decorators, {
 				kind: "method",
 				name: "stat",
@@ -330,10 +351,12 @@ let WorkspaceFiles = (() => {
 		static inject = [
 			"fs",
 			"sandboxPolicy",
+			"sessions",
 			"typert"
 		];
 		static Config = z.object({
 			maxBytes: z.number().step(1).min(1).default(2 * 1024 * 1024),
+			maxFileBytes: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER - 1).default(32 * 1024 * 1024),
 			maxLines: z.number().step(1).min(1).default(5e3),
 			maxEntries: z.number().step(1).min(1).default(2e3)
 		});
@@ -346,18 +369,36 @@ let WorkspaceFiles = (() => {
 			super(ctx, "workspaceFiles");
 			this.config = config;
 			this.feed = new WorkspaceChangeFeed(ctx);
+			ctx.inject(["sessions", "typert"], (scope) => {
+				scope.typert.lookups.register("workspaceFileScope", {
+					parameter: "workspaceFileScope",
+					wire: "workspaceFileScopeId",
+					hostTypeSymbol: "@deepseek-ai/dsh-api-workspace-files#WorkspaceFileScope",
+					wireTypeSymbol: "@deepseek-ai/dsh-session/types#SessionId",
+					resolve: async (sessionId) => {
+						const live = scope.sessions.get(sessionId)?.header;
+						const stored = live === void 0 ? await scope.get("sessionPersistence")?.stat(sessionId) : void 0;
+						const header = live ?? stored?.header;
+						if (header === void 0) return void 0;
+						return {
+							sessionId,
+							workspaceRoot: header.cwd ?? scope.sandboxPolicy.workspaceRoot
+						};
+					}
+				});
+			});
 		}
 		/**
-		* Read one page of lines from a UTF-8 text file inside the Agent's workspace.
-		* @param agent - target Agent resolved from the Session identity on the wire.
-		* @param path - workspace path, absolute or relative to the workspace root.
+		* Read one page of lines from a UTF-8 file readable by the filesystem backend.
+		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
+		* @param path - absolute path or path relative to the workspace root; files outside it are allowed.
 		* @param range - the line window; omitted fields take the page defaults.
 		* @param signal - caller cancellation.
 		* @returns the page, the file's version at the stat before it, and whether it reaches the last line.
 		*/
-		async read(agent, path, range, signal) {
+		async read(workspaceFileScope, path, range, signal) {
 			const { offset, limit } = this.resolvePage(range);
-			const { target, info } = await this.locateFile(agent, path, signal);
+			const { target, info } = await this.locateFile(workspaceFileScope, path, signal);
 			const page = await this.cutPage(target, offset, limit, signal, path);
 			if (page.text.includes(NUL)) throw new RemoteError("workspace-file/not-text", `"${path}" contains NUL bytes`, { path });
 			return {
@@ -369,17 +410,17 @@ let WorkspaceFiles = (() => {
 			};
 		}
 		/**
-		* Read one byte window of a regular file inside the Agent's workspace: raw
+		* Read one byte window of a regular file readable by the filesystem backend: raw
 		* bytes, no text decoding and no binary rejection.
-		* @param agent - target Agent resolved from the Session identity on the wire.
-		* @param path - workspace path, absolute or relative to the workspace root.
+		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
+		* @param path - absolute path or path relative to the workspace root; files outside it are allowed.
 		* @param range - the byte window; omitted fields take the window defaults.
 		* @param signal - caller cancellation.
 		* @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte.
 		*/
-		async readBytes(agent, path, range, signal) {
+		async readBytes(workspaceFileScope, path, range, signal) {
 			const { offset, length } = this.resolveWindow(range, path);
-			const { target, info } = await this.locateFile(agent, path, signal);
+			const { target, info } = await this.locateFile(workspaceFileScope, path, signal);
 			const data = await this.ctx.fs.readByteRange(target, {
 				offset,
 				length
@@ -393,25 +434,70 @@ let WorkspaceFiles = (() => {
 			};
 		}
 		/**
+		* Read a complete regular file as bytes, subject to the configured full-file cap.
+		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
+		* @param path - absolute or workspace-relative file path.
+		* @param signal - caller cancellation.
+		* @returns one complete base64 window with offset zero and eof true; oversized files fail with too-large.
+		*/
+		async readAll(workspaceFileScope, path, signal) {
+			const { target, info } = await this.locateFile(workspaceFileScope, path, signal);
+			const limit = this.config.maxFileBytes;
+			if (info.size !== void 0 && info.size > limit) throw new RemoteError("workspace-file/too-large", `"${path}" exceeds the ${limit} byte full-file cap`, {
+				path,
+				limit
+			});
+			const data = await this.ctx.fs.readByteRange(target, {
+				offset: 0,
+				length: limit + 1
+			}, signal);
+			if (data.length > limit) throw new RemoteError("workspace-file/too-large", `"${path}" exceeds the ${limit} byte full-file cap`, {
+				path,
+				limit
+			});
+			return {
+				...this.statOf(target, info),
+				offset: 0,
+				data: Buffer.from(data).toString("base64"),
+				eof: true
+			};
+		}
+		/**
+		* Read a complete file relative to another file's directory, including outside the workspace.
+		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
+		* @param path - base file, absolute or workspace-relative.
+		* @param relativePath - relative filesystem path, not a URL or absolute path.
+		* @param signal - caller cancellation.
+		* @returns the complete related file using the ordinary file-size and access checks.
+		*/
+		async readRelated(workspaceFileScope, path, relativePath, signal) {
+			const relative = relativePath.replace(/\\/g, "/");
+			if (relative.length === 0 || relative.startsWith("/") || /^[a-z][a-z\d+.-]*:/iu.test(relative) || relative.includes(NUL)) throw new RemoteError("gateway/bad-request", "relativePath must be a relative filesystem path", {});
+			const { target } = await this.locateFile(workspaceFileScope, path, signal);
+			const absolute = this.ctx.fs.processPath(target);
+			const paths = absolute.startsWith("/") ? posix : win32;
+			return this.readAll(workspaceFileScope, paths.resolve(paths.dirname(absolute), relative), signal);
+		}
+		/**
 		* Report one regular file's identity, version, and size without its content.
-		* @param agent - target Agent resolved from the Session identity on the wire.
-		* @param path - workspace path, absolute or relative to the workspace root.
+		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
+		* @param path - absolute path or path relative to the workspace root; files outside it are allowed.
 		* @param signal - caller cancellation.
 		* @returns the file's absolute path, current version, and byte size.
 		*/
-		async stat(agent, path, signal) {
-			const { target, info } = await this.locateFile(agent, path, signal);
+		async stat(workspaceFileScope, path, signal) {
+			const { target, info } = await this.locateFile(workspaceFileScope, path, signal);
 			return this.statOf(target, info);
 		}
 		/**
-		* List the direct children of one directory inside the Agent's workspace.
-		* @param agent - target Agent resolved from the Session identity on the wire.
+		* List the direct children of one directory inside the Session's workspace.
+		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
 		* @param path - workspace path, absolute or relative to the workspace root.
 		* @param signal - caller cancellation.
 		* @returns the directory's children in the backend's stable name order, bounded by the entry cap.
 		*/
-		async list(agent, path, signal) {
-			const { root, workspaceRoot, entry } = await this.inspect(agent, path, signal);
+		async list(workspaceFileScope, path, signal) {
+			const { root, workspaceRoot, entry } = await this.inspect(workspaceFileScope, path, signal);
 			if (entry.type !== "directory") throw new RemoteError("workspace-file/not-directory", `"${path}" is a ${entry.type}`, {
 				path,
 				kind: entry.type
@@ -425,16 +511,16 @@ let WorkspaceFiles = (() => {
 			};
 		}
 		/**
-		* Stream every `fs/observed` observation of a file inside the Agent's
-		* workspace. Only Agent filesystem operations report here; the OS is not
-		* watched.
-		* @param agent - target Agent resolved from the Session identity on the wire.
+		* Stream every `fs/observed` observation of a file inside the Session's
+		* workspace. Only instrumented filesystem operations report here; the OS is
+		* not watched.
+		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
 		* @param signal - generation cancellation.
 		* @returns `ready` once the Host observation queue is active and the workspace
 		*   root is resolved, then queued and live observations in emission order.
 		*/
-		changes(agent, signal) {
-			return this.feed.follow(this.workspaceRootOf(agent), signal);
+		changes(workspaceFileScope, signal) {
+			return this.feed.follow(workspaceFileScope.workspaceRoot, signal);
 		}
 		/** Apply the page defaults and caps here, so the request never carries them implicitly. */
 		resolvePage(range) {
@@ -461,25 +547,12 @@ let WorkspaceFiles = (() => {
 			};
 		}
 		/**
-		* The workspace root comes from the policy, not from the backend's own cwd
-		* default: the `minimal` preset shadows the host provider with a bare
-		* `fs-local` whose cwd differs, and resolving explicitly makes the answer
-		* the same whichever instance answers.
-		*/
-		workspaceRootOf(agent) {
-			return this.ctx.sandboxPolicy.resolve({ session: agent.session }).workspaceRoot;
-		}
-		/**
-		* Gates 1 and 2 up to the point where the path's own type is known. The
-		* path is inspected before containment is decided, so a caller learns whether
-		* an outside path exists and what kind it is before `outside-workspace`
-		* refuses it; the caller is the Session's own owner, who can read the Host
-		* through the Agent anyway, and the accepted cost buys one `lstat` gate for
-		* every method instead of two resolution orders.
+		* Inspect the requested path itself before resolution follows its final
+		* component. Directory containment is checked separately by `list`.
 		*/
-		async inspect(agent, path, signal) {
+		async inspect(workspaceFileScope, path, signal) {
 			if (path.length === 0) throw new RemoteError("gateway/bad-request", "path is required", {});
-			const workspaceRoot = this.workspaceRootOf(agent);
+			const { workspaceRoot } = workspaceFileScope;
 			const root = await this.ctx.fs.resolve(workspaceRoot, { signal });
 			const entry = await this.ctx.fs.lstat(path, { cwd: workspaceRoot }, signal);
 			if (entry === void 0) throw new RemoteError("workspace-file/not-found", `no entry at "${path}"`, { path });
@@ -503,13 +576,16 @@ let WorkspaceFiles = (() => {
 		* and size. The stat re-checks what `lstat` saw: the file may have gone or
 		* changed kind in between.
 		*/
-		async locateFile(agent, path, signal) {
-			const { root, workspaceRoot, entry } = await this.inspect(agent, path, signal);
+		async locateFile(workspaceFileScope, path, signal) {
+			const { workspaceRoot, entry } = await this.inspect(workspaceFileScope, path, signal);
 			if (entry.type !== "file") throw new RemoteError("workspace-file/not-regular-file", `"${path}" is a ${entry.type}`, {
 				path,
 				kind: entry.type
 			});
-			const target = await this.confine(root, workspaceRoot, path, signal);
+			const target = await this.ctx.fs.resolve(path, {
+				cwd: workspaceRoot,
+				signal
+			});
 			const info = await this.ctx.fs.stat(target, signal);
 			if (info === void 0) throw new RemoteError("workspace-file/not-found", `no entry at "${path}"`, { path });
 			if (info.type !== "file") throw new RemoteError("workspace-file/not-regular-file", `"${path}" is a ${info.type}`, {