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

package/lib/types/index.js

@@ -140,8 +140,6 @@ let WorkspaceFiles = (() => {
     let _instanceExtraInitializers = [];
     let _read_decorators;
     let _readBytes_decorators;
-    let _readAll_decorators;
-    let _readRelated_decorators;
     let _stat_decorators;
     let _list_decorators;
     let _changes_decorators;
@@ -150,15 +148,11 @@ 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);
@@ -221,30 +215,23 @@ 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 readable by the filesystem backend: raw
-         * bytes, no text decoding and no binary rejection.
+         * Read a complete regular file or one byte range without text decoding.
          * @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(workspaceFileScope, path, range, signal) {
-            const { offset, length } = this.resolveWindow(range, path);
-            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 path - target path, absolute or workspace-relative; relative to the base file's directory when provided.
+         * @param options - optional base file and range; without a range the complete-file cap applies.
          * @param signal - caller cancellation.
-         * @returns one complete base64 window with offset zero and eof true; oversized files fail with too-large.
+         * @returns native bytes with the file's version and size at the preceding stat, byte offset, and EOF marker.
          */
-        async readAll(workspaceFileScope, path, signal) {
-            const { target, info } = await this.locateFile(workspaceFileScope, path, signal);
+        async readBytes(workspaceFileScope, path, options, signal) {
+            const window = options.range === undefined ? undefined : this.resolveWindow(options.range, path);
+            const resolved = options.baseFile === undefined ? path : await this.relativePath(workspaceFileScope, options.baseFile, path, signal);
+            const { target, info } = await this.locateFile(workspaceFileScope, resolved, signal);
+            if (window !== undefined) {
+                const { offset, length } = window;
+                const data = await this.ctx.fs.readByteRange(target, window, signal);
+                const eof = info.size === undefined ? data.length < length : offset + data.length >= info.size;
+                return { ...this.statOf(target, info), offset, data, eof };
+            }
             const limit = this.config.maxFileBytes;
             const data = await this.ctx.fs.readBytes(target, signal, limit).catch((cause) => {
                 if (typeof cause === 'object' && cause !== null && 'code' in cause && cause.code === 'FS_TOO_LARGE') {
@@ -252,25 +239,7 @@ let WorkspaceFiles = (() => {
                 }
                 throw cause;
             });
-            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);
+            return { ...this.statOf(target, info), offset: 0, data, eof: true };
         }
         /**
          * Report one regular file's identity, version, and size without its content.
@@ -304,16 +273,26 @@ let WorkspaceFiles = (() => {
             };
         }
         /**
-         * Stream every `fs/observed` observation of a file inside the Session's
-         * workspace. Only instrumented filesystem operations report here; the OS is
-         * not watched.
+         * Watch one file or a directory's direct entries in the Session's filesystem.
+         * Files use the backend's read authority; directories remain workspace-scoped.
          * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
+         * @param path - target path; the Host determines its type and confines directories to the workspace.
          * @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.
+         * @returns `ready` once the target watch is active, then current metadata for queued and live invalidations.
+         * @throws RemoteError when watching is unavailable or a directory is outside the workspace.
          */
-        changes(workspaceFileScope, signal) {
-            return this.feed.follow(workspaceFileScope.workspaceRoot, signal);
+        changes(workspaceFileScope, path, signal) {
+            return this.feed.follow(workspaceFileScope.workspaceRoot, path, signal);
+        }
+        async relativePath(scope, baseFile, path, signal) {
+            const relative = path.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', 'path must be relative when baseFile is provided', {});
+            }
+            const { target } = await this.locateFile(scope, baseFile, signal);
+            const absolute = this.ctx.fs.processPath(target);
+            const paths = absolute.startsWith('/') ? posix : win32;
+            return paths.resolve(paths.dirname(absolute), relative);
         }
         /** Apply the page defaults and caps here, so the request never carries them implicitly. */
         resolvePage(range) {

package/lib/types/types.d.ts

@@ -60,15 +60,22 @@ export interface WorkspaceByteRange {
     /** Largest number of bytes in the window. Defaults to, and may not exceed, the configured `maxBytes`. */
     readonly length?: number;
 }
+/** Target resolution and optional byte range for one binary file read. */
+export interface WorkspaceByteReadOptions {
+    /** Byte window; omit to read the complete file under the configured `maxFileBytes` cap. */
+    readonly range?: WorkspaceByteRange;
+    /** Base file, absolute or workspace-relative; resolve the relative target from its directory. */
+    readonly baseFile?: string;
+}
 /**
  * One byte window of a workspace file as a Client reads it: raw bytes, no text
  * decoding and no binary rejection. `bytes` is the complete file's size.
  */
-export interface WorkspaceFileBytes extends WorkspaceFileStat {
+export interface WorkspaceFileBytes<Data extends Uint8Array = Uint8Array> extends WorkspaceFileStat {
     /** First byte of the window, as requested. */
     readonly offset: number;
-    /** The window's bytes in base64; empty when `offset` lies at or past the file's end. */
-    readonly data: string;
+    /** Native file bytes; empty at or past EOF. */
+    readonly data: Data;
     /** Whether the window includes the file's last byte. */
     readonly eof: boolean;
 }
@@ -103,25 +110,25 @@ export interface WorkspaceDirectoryListing {
     readonly truncated: boolean;
 }
 /**
- * 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.
+ * Current target metadata after a filesystem invalidation. File consumers may
+ * ignore an already known version; directory consumers relist on every frame
+ * because a child's metadata can change without changing the directory version.
  */
 export type WorkspaceFileChange = {
-    /** Absolute path of the observed file, in the same form as {@link WorkspaceFileStat.absolutePath}. */
+    /** Absolute target path, in the same form as {@link WorkspaceFileStat.absolutePath}. */
     readonly absolutePath: string;
-    /** Opaque freshness token after the observed operation; never parsed. */
+    /** Opaque freshness token from the current stat; never parsed. */
     readonly version: string;
 } | {
-    /** Absolute path of the observed file, in the same form as {@link WorkspaceFileStat.absolutePath}. */
+    /** Absolute target path, in the same form as {@link WorkspaceFileStat.absolutePath}. */
     readonly absolutePath: string;
-    /** The file was observed to be gone. */
+    /** The target was observed to be gone. */
     readonly absent: true;
 };
 /**
  * One frame of a workspace file watch generation. `ready` confirms that the
- * Host is observing filesystem operations and has resolved the workspace
- * root; observations queued during that resolution follow as `change` frames.
+ * Host has initialized the target watcher; queued and live invalidations
+ * follow as `change` frames with current target metadata.
  */
 export type WorkspaceFileWatchFrame = {
     readonly kind: 'ready';
@@ -131,11 +138,15 @@ export type WorkspaceFileWatchFrame = {
 };
 declare module '@deepseek-ai/dsh-typert-protocol' {
     interface RemoteErrorDetailsMap {
+        /** The filesystem provider cannot initialize a watch for this target. */
+        'workspace-file/watch-unsupported': {
+            readonly path: string;
+        };
         /** No entry exists at that path inside the workspace. */
         'workspace-file/not-found': {
             readonly path: string;
         };
-        /** The directory listing path resolves outside the session's workspace root. */
+        /** The directory listing or watch 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.6-alpha.2",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -49,23 +49,25 @@
   "license": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-deque": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.2",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/dsh-deque": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.7-alpha.1",
+    "@deepseek-ai/schemastery": "^3.18.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-api-gateway": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-resources": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-util-workspace-path": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-api-gateway": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-resources": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-fs": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-remote-mock": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-util-workspace-path": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.7-alpha.1"
   },
   "files": [
     "lib/index.js",