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

package/lib/types/index.js

@@ -1,20 +1,14 @@
 /**
- * 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
@@ -58,6 +52,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
+import { posix, win32 } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { WorkspaceChangeFeed } from "./changes.js";
@@ -139,12 +134,14 @@ function directoryEntry(child) {
         ...child.size === undefined ? {} : { 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;
@@ -153,20 +150,25 @@ 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' })];
             __esDecorate(this, null, _read_decorators, { kind: "method", name: "read", static: false, private: false, access: { has: obj => "read" in obj, get: obj => obj.read }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _readBytes_decorators, { kind: "method", name: "readBytes", static: false, private: false, access: { has: obj => "readBytes" in obj, get: obj => obj.readBytes }, 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", static: false, private: false, access: { has: obj => "stat" in obj, get: obj => obj.stat }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _changes_decorators, { kind: "method", name: "changes", static: false, private: false, access: { has: obj => "changes" in obj, get: obj => obj.changes }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         config = __runInitializers(this, _instanceExtraInitializers);
-        static inject = ['fs', 'sandboxPolicy', 'typert'];
+        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(5000),
             maxEntries: z.number().step(1).min(1).default(2000),
         });
@@ -179,18 +181,39 @@ 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 === undefined
+                            ? await scope.get('sessionPersistence')?.stat(sessionId)
+                            : undefined;
+                        const header = live ?? stored?.header;
+                        if (header === undefined)
+                            return undefined;
+                        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 });
@@ -198,41 +221,78 @@ let WorkspaceFiles = (() => {
             return { ...this.statOf(target, info), offset, text: page.text, lines: page.lines, eof: page.eof };
         }
         /**
-         * 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 }, signal);
             const eof = info.size === undefined ? data.length < length : offset + data.length >= info.size;
             return { ...this.statOf(target, info), offset, data: Buffer.from(data).toString('base64'), eof };
         }
+        /**
+         * 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 !== undefined && 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 });
             }
@@ -245,16 +305,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) {
@@ -278,26 +338,13 @@ let WorkspaceFiles = (() => {
             return { offset, length };
         }
         /**
-         * 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.
+         * Inspect the requested path itself before resolution follows its final
+         * component. Directory containment is checked separately by `list`.
          */
-        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.
-         */
-        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 });
             // Gate on the path itself before anything follows it.
             const entry = await this.ctx.fs.lstat(path, { cwd: workspaceRoot }, signal);
@@ -319,12 +366,12 @@ 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 === undefined) {
                 throw new RemoteError('workspace-file/not-found', `no entry at "${path}"`, { path });

package/lib/types/types.d.ts

@@ -103,9 +103,9 @@ export interface WorkspaceDirectoryListing {
     readonly truncated: boolean;
 }
 /**
- * One observation of a workspace file made by an Agent's own filesystem
- * operation. Frames report observations, not deltas: a consumer already holding
- * `version` learns nothing new from the frame and can ignore it.
+ * One observation of a workspace file made by an instrumented filesystem
+ * operation. Frames report observations, not deltas: a consumer already
+ * holding `version` learns nothing new from the frame and can ignore it.
  */
 export type WorkspaceFileChange = {
     /** Absolute path of the observed file, in the same form as {@link WorkspaceFileStat.absolutePath}. */
@@ -135,7 +135,7 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
         'workspace-file/not-found': {
             readonly path: string;
         };
-        /** The path resolves outside the session's workspace root. */
+        /** The directory listing path resolves outside the session's workspace root. */
         'workspace-file/outside-workspace': {
             readonly path: string;
         };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-api-workspace-files",
   "description": "Workspace file service and Client resource provider: bounded reads, directory listing, and live metadata over the workspaceFiles Remote namespace",
-  "version": "0.1.5-alpha.1",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -41,7 +41,6 @@
     "client": {
       "inject": [
         "@deepseek-ai/dsh-api-gateway",
-        "@deepseek-ai/dsh-api-session-controller",
         "@deepseek-ai/dsh-client-resources"
       ],
       "platform": "web"
@@ -50,24 +49,23 @@
   "license": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-alpha.1",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-deque": "^0.1.5-alpha.1"
+    "@deepseek-ai/dsh-deque": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-api-gateway": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-client-resources": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-fs": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-session": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-util-workspace-path": "^0.1.5-alpha.1"
+    "@deepseek-ai/dsh-api-gateway": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-client-resources": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-util-workspace-path": "^0.1.5-alpha.2"
   },
   "files": [
     "lib/index.js",