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

package/lib/types/changes.d.ts

@@ -1,26 +1,23 @@
 /**
- * Producer of the `changes` stream: every `fs/observed` emission whose target
- * lies inside a generation's workspace root becomes one frame of that
- * 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.
+ * Target-scoped filesystem watches and `fs/observed` invalidations for `changes`.
+ * Each generation sends `ready` after watcher initialization, then reads current
+ * target metadata for matching queued and live invalidations.
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { WorkspaceFileWatchFrame } from './types.ts';
-/** Owns `fs/observed` observation and every open `changes` generation. */
+/** Owns target watches, instrumented observations, and every open `changes` generation. */
 export declare class WorkspaceChangeFeed {
     private readonly ctx;
     private readonly followers;
     /** @param ctx - Host context carrying the filesystem the observations come from. */
     constructor(ctx: Context);
     /**
-     * Open one generation reporting observations inside `workspaceRoot`.
+     * Open one target watch; directory targets remain inside `workspaceRoot`.
      * @param workspaceRoot - the session's workspace root path.
+     * @param path - target path, resolved relative to the workspace root; Host metadata determines its type.
      * @param signal - generation cancellation.
-     * @returns `ready` after observation is active and the root resolves, then
-     *   observations made after the generation was first pulled, in emission order.
+     * @returns `ready` after watching starts, then current metadata for target invalidations.
      */
-    follow(workspaceRoot: string, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>;
+    follow(workspaceRoot: string, path: string, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>;
 }
 //# sourceMappingURL=changes.d.ts.map

package/lib/types/changes.js

@@ -1,13 +1,11 @@
 /**
- * Producer of the `changes` stream: every `fs/observed` emission whose target
- * lies inside a generation's workspace root becomes one frame of that
- * 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.
+ * Target-scoped filesystem watches and `fs/observed` invalidations for `changes`.
+ * Each generation sends `ready` after watcher initialization, then reads current
+ * target metadata for matching queued and live invalidations.
  */
 import { Deque } from '@deepseek-ai/dsh-deque';
-/** Owns `fs/observed` observation and every open `changes` generation. */
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+/** Owns target watches, instrumented observations, and every open `changes` generation. */
 export class WorkspaceChangeFeed {
     ctx;
     followers = new Set();
@@ -18,92 +16,154 @@ export class WorkspaceChangeFeed {
             for (const follower of this.followers)
                 follower.push([target, observation]);
         });
-        ctx.effect(() => () => {
-            for (const follower of this.followers)
-                follower.close();
+        ctx.effect(() => async () => {
+            const followers = [...this.followers];
+            await Promise.all(followers.map(follower => follower.close()));
             this.followers.clear();
         }, 'workspace-files.changes');
     }
     /**
-     * Open one generation reporting observations inside `workspaceRoot`.
+     * Open one target watch; directory targets remain inside `workspaceRoot`.
      * @param workspaceRoot - the session's workspace root path.
+     * @param path - target path, resolved relative to the workspace root; Host metadata determines its type.
      * @param signal - generation cancellation.
-     * @returns `ready` after observation is active and the root resolves, then
-     *   observations made after the generation was first pulled, in emission order.
+     * @returns `ready` after watching starts, then current metadata for target invalidations.
      */
-    async *follow(workspaceRoot, signal) {
+    async *follow(workspaceRoot, path, signal) {
         signal.throwIfAborted();
-        // Registered before the root resolves, so nothing observed while it does is
-        // missed; the root only filters at drain time.
-        const follower = new ChangeFollower();
+        // Instrumented observations remain queued while the target resolves.
+        const follower = new ChangeFollower(() => {
+            signal.removeEventListener('abort', cancel);
+            this.followers.delete(follower);
+        });
+        signal = AbortSignal.any([signal, follower.controller.signal]);
+        const aborted = () => signal.aborted;
+        const cancel = () => {
+            void follower.close().catch((error) => { this.ctx.logger.error(error); });
+        };
+        signal.addEventListener('abort', cancel, { once: true });
         this.followers.add(follower);
+        let unwatch;
         try {
-            // Under the generation's signal, so a consumer leaving mid-resolve on a slow
-            // backend releases the follower now rather than when the resolve settles;
-            // a rejection the abort caused is the quiet end every other abort takes here.
+            // Setup shares cancellation, so a late resolution cannot acquire a watcher.
             const root = await this.ctx.fs.resolve(workspaceRoot, { signal }).catch((error) => {
-                if (signal.aborted)
+                if (aborted())
+                    return undefined;
+                throw error;
+            });
+            if (root === undefined || aborted() || follower.isClosed)
+                return;
+            const target = await this.ctx.fs.resolve(path, { cwd: workspaceRoot, signal }).catch((error) => {
+                if (aborted())
                     return undefined;
                 throw error;
             });
-            if (root === undefined || signal.aborted || follower.isClosed)
+            if (target === undefined || aborted())
+                return;
+            const stat = async () => {
+                const info = await this.ctx.fs.stat(target, signal).catch((error) => {
+                    if (aborted())
+                        return undefined;
+                    throw error;
+                });
+                if (info?.type === 'directory' && !this.ctx.fs.contains(root, target)) {
+                    throw new RemoteError('workspace-file/outside-workspace', 'Directory is outside the workspace', { path });
+                }
+                return info;
+            };
+            await stat();
+            if (aborted())
+                return;
+            try {
+                unwatch = await this.ctx.fs.watch(target, (error) => {
+                    if (error !== undefined)
+                        follower.fail(error);
+                    else if (!follower.isClosed)
+                        follower.push([target]);
+                }, signal);
+                if (follower.error !== undefined)
+                    throw follower.error;
+            }
+            catch (error) {
+                if (aborted() && follower.error === undefined)
+                    return;
+                const failure = follower.error ?? error;
+                throw new RemoteError('workspace-file/watch-unsupported', failure instanceof Error ? failure.message : String(failure), { path });
+            }
+            follower.initialized.resolve(unwatch);
+            if (aborted())
                 return;
             yield { kind: 'ready' };
-            for await (const [target, observation] of follower.read(signal)) {
-                if (!this.ctx.fs.contains(root, target))
+            for await (const [observed] of follower.read()) {
+                if (observed.targetKey !== target.targetKey)
                     continue;
+                const info = await stat();
+                if (aborted())
+                    return;
                 const absolutePath = this.ctx.fs.processPath(target);
                 yield {
                     kind: 'change',
-                    change: observation.kind === 'present'
-                        ? { absolutePath, version: observation.version }
+                    change: info !== undefined
+                        ? { absolutePath, version: info.version }
                         : { absolutePath, absent: true },
                 };
             }
         }
         finally {
-            this.followers.delete(follower);
-            follower.close();
+            follower.initialized.resolve(unwatch);
+            await follower.close();
         }
     }
 }
 /** One generation's queue: observations wait here until its consumer pulls them. */
 class ChangeFollower {
+    release;
+    controller = new AbortController();
+    initialized = Promise.withResolvers();
+    error;
     queue = new Deque();
     wake;
     closed = false;
-    /** Whether the generation was closed while its workspace root resolved. */
+    closing;
+    constructor(release) {
+        this.release = release;
+    }
+    /** Whether this generation has stopped accepting invalidations. */
     get isClosed() {
         return this.closed;
     }
     push(observed) {
+        if (this.closed)
+            return;
         this.queue.pushBack(observed);
         this.wake?.();
     }
     close() {
+        if (this.closing !== undefined)
+            return this.closing;
         this.closed = true;
+        this.closing = this.initialized.promise.then(unwatch => unwatch?.()).finally(this.release);
+        this.controller.abort();
         this.wake?.();
+        return this.closing;
+    }
+    fail(error) {
+        this.error = error;
+        this.controller.abort();
     }
     /** Drain until closed or aborted; anything still queued then is dropped with the generation. */
-    async *read(signal) {
-        const abort = () => { this.close(); };
-        signal.addEventListener('abort', abort, { once: true });
-        if (signal.aborted)
-            abort();
-        try {
-            while (!this.closed) {
-                const observed = this.queue.popFront();
-                if (observed !== undefined) {
-                    yield observed;
-                    continue;
-                }
-                await new Promise((resolve) => { this.wake = resolve; });
-                this.wake = undefined;
+    async *read() {
+        while (!this.closed) {
+            const observed = this.queue.popFront();
+            if (observed !== undefined) {
+                yield observed;
+                continue;
             }
+            await new Promise((resolve) => { this.wake = resolve; });
+            this.wake = undefined;
         }
-        finally {
-            signal.removeEventListener('abort', abort);
-        }
+        if (this.error !== undefined)
+            throw this.error;
     }
 }
 //# sourceMappingURL=changes.js.map

package/lib/types/client/change-feed.d.ts

@@ -1,11 +1,11 @@
 /**
- * One Host `changes` subscription per session, fanned out to the open files of
- * that session.
+ * One Host `changes` subscription per Session and requested path, shared by
+ * that target's open resources.
  *
- * The Host reports every agent write in a session on one stream; each open file
- * wants only its own. The feed opens the session stream when the first follower
+ * The Host reports invalidations from filesystem watches and instrumented writes.
+ * The feed opens the target stream when the first follower
  * arrives, hands each frame to the followers of its path, and disposes the
- * stream when the last follower leaves. A follower buffers session changes
+ * stream when the last follower leaves. A follower buffers target changes
  * until `stat` supplies its Host absolute path, then filters queued and live
  * frames by that path, with `\\` normalized to `/`.
  */
@@ -50,7 +50,7 @@ declare class Follower implements AsyncIterable<WorkspaceFileNotice> {
     [Symbol.asyncIterator](): AsyncIterator<WorkspaceFileNotice>;
 }
 /**
- * Per-session fan-out of the Host's workspace file change stream.
+ * Per-target sharing of the Host's workspace file change streams.
  *
  * Owned by the provider; one instance serves every session of the Client.
  */
@@ -58,7 +58,7 @@ export declare class ChangeFeed {
     private readonly remote;
     /** Live feeds only: a feed removes itself when its stream closes. */
     private readonly sessions;
-    /** Streams still closing, by session: the session's next feed opens after its predecessor has settled. */
+    /** Streams still closing, by Session and path; a successor waits for its predecessor. */
     private readonly closing;
     /**
      * @param remote - the Remote face carrying `$stream` and `workspaceFiles.changes`.
@@ -69,18 +69,19 @@ export declare class ChangeFeed {
      *
      * The follower is registered on call, not on first pull. Changes delivered
      * to this Client are queued while stat is pending. The first follower starts
-     * the session's local `changes` call. The iterable ends
-     * when `signal` aborts or when the session stream is gone; ending it early
+     * target's local `changes` call. The iterable ends
+     * when `signal` aborts or when the target stream is gone; ending it early
      * (`break`, `return`) unregisters the follower as well, and the last follower
-     * of a session disposes its stream. Await a true `ready` result before stat
+     * of a target disposes its stream. Await a true `ready` result before stat
      * so the Host subscription is active, then bind each stat's absolute path. Until binding,
-     * any session write can trigger a retry; after binding, only matching queued
+     * any target invalidation can trigger a retry; after binding, only matching queued
      * and live changes pass.
-     * @param sessionId - the session whose workspace holds the file.
+     * @param sessionId - the Session providing the file's read authority.
+     * @param path - requested file path; followers share a stream only for the same Session and path.
      * @param signal - ends the follow.
      * @returns a single-consumer subscription with Host-path binding and explicit disposal.
      */
-    follow(sessionId: SessionId, signal: AbortSignal): Follower;
+    follow(sessionId: SessionId, path: string, signal: AbortSignal): Follower;
     /**
      * Wait for every stream that is still closing, so an owner tearing down
      * leaves no Host stream behind.

package/lib/types/client/change-feed.js

@@ -61,7 +61,7 @@ class Follower {
             while (true) {
                 const next = this.pending.shift();
                 if (next !== undefined) {
-                    if (this.hostKey === undefined || next.key === this.hostKey)
+                    if (next.notice.kind === 'refresh' || this.hostKey === undefined || next.key === this.hostKey)
                         yield next.notice;
                     continue;
                 }
@@ -76,31 +76,32 @@ class Follower {
         }
     }
 }
-/** The stream and followers of one session. */
+/** The stream and followers of one Session and requested path. */
 class SessionFeed {
     onClose;
     followers = new Set();
     stream;
     closed = false;
     started = false;
+    acknowledged = false;
     /**
      * @param remote - the Remote face carrying `workspaceFiles.changes`.
-     * @param sessionId - the session whose writes this feed follows.
-     * @param after - the previous feed of this session still closing, if any; the stream opens once it has settled.
+     * @param sessionId - the Session whose filesystem this feed observes.
+     * @param path - target path submitted to the Host.
+     * @param after - the previous feed of this target still closing, if any; the stream opens once it has settled.
      * @param onClose - called once when the stream is gone, whatever the cause, with the dispose that is closing it.
      */
-    constructor(remote, sessionId, after, onClose) {
+    constructor(remote, sessionId, path, after, onClose) {
         this.onClose = onClose;
         this.stream = remote.$stream({
             name: `workspace file changes of ${sessionId}`,
-            // A predecessor still closing finishes first, so one session never has
+            // A predecessor still closing finishes first, so one target never has
             // two Host streams open at once.
             open: (signal) => {
                 this.started = false;
-                return openAfter(after, () => remote.workspaceFiles.changes(sessionId, signal));
+                return openAfter(after, () => remote.workspaceFiles.changes(sessionId, path, signal));
             },
-            // A normal end means the Host closed the session's feed: the session is
-            // gone or the Host is shutting down, so there is nothing to reopen.
+            // A normal end means the Host closed the target's feed.
             ended: () => new Error(`workspace file changes of ${sessionId} ended`),
         });
         void this.pump();
@@ -131,8 +132,12 @@ class SessionFeed {
                     case 'ready':
                         item.accept();
                         this.started = true;
-                        for (const follower of this.followers)
+                        for (const follower of this.followers) {
                             follower.start();
+                            if (this.acknowledged)
+                                follower.push({ kind: 'refresh' }, '');
+                        }
+                        this.acknowledged = true;
                         break;
                     case 'change': {
                         const key = keyOf(frame.change.absolutePath);
@@ -187,7 +192,7 @@ function assertNever(frame) {
     throw new Error(`Unexpected workspace file watch frame: ${JSON.stringify(frame)}`);
 }
 /**
- * Per-session fan-out of the Host's workspace file change stream.
+ * Per-target sharing of the Host's workspace file change streams.
  *
  * Owned by the provider; one instance serves every session of the Client.
  */
@@ -195,7 +200,7 @@ export class ChangeFeed {
     remote;
     /** Live feeds only: a feed removes itself when its stream closes. */
     sessions = new Map();
-    /** Streams still closing, by session: the session's next feed opens after its predecessor has settled. */
+    /** Streams still closing, by Session and path; a successor waits for its predecessor. */
     closing = new Map();
     /**
      * @param remote - the Remote face carrying `$stream` and `workspaceFiles.changes`.
@@ -208,19 +213,20 @@ export class ChangeFeed {
      *
      * The follower is registered on call, not on first pull. Changes delivered
      * to this Client are queued while stat is pending. The first follower starts
-     * the session's local `changes` call. The iterable ends
-     * when `signal` aborts or when the session stream is gone; ending it early
+     * target's local `changes` call. The iterable ends
+     * when `signal` aborts or when the target stream is gone; ending it early
      * (`break`, `return`) unregisters the follower as well, and the last follower
-     * of a session disposes its stream. Await a true `ready` result before stat
+     * of a target disposes its stream. Await a true `ready` result before stat
      * so the Host subscription is active, then bind each stat's absolute path. Until binding,
-     * any session write can trigger a retry; after binding, only matching queued
+     * any target invalidation can trigger a retry; after binding, only matching queued
      * and live changes pass.
-     * @param sessionId - the session whose workspace holds the file.
+     * @param sessionId - the Session providing the file's read authority.
+     * @param path - requested file path; followers share a stream only for the same Session and path.
      * @param signal - ends the follow.
      * @returns a single-consumer subscription with Host-path binding and explicit disposal.
      */
-    follow(sessionId, signal) {
-        const feed = signal.aborted ? undefined : this.feedOf(sessionId);
+    follow(sessionId, path, signal) {
+        const feed = signal.aborted ? undefined : this.feedOf(sessionId, path);
         const leave = () => {
             signal.removeEventListener('abort', leave);
             follower.end();
@@ -244,20 +250,21 @@ export class ChangeFeed {
     async settle() {
         await Promise.all(this.closing.values());
     }
-    feedOf(sessionId) {
-        const existing = this.sessions.get(sessionId);
+    feedOf(sessionId, path) {
+        const key = JSON.stringify([sessionId, path]);
+        const existing = this.sessions.get(key);
         if (existing !== undefined)
             return existing;
-        const feed = new SessionFeed(this.remote, sessionId, this.closing.get(sessionId), (closed) => {
-            this.sessions.delete(sessionId);
+        const feed = new SessionFeed(this.remote, sessionId, path, this.closing.get(key), (closed) => {
+            this.sessions.delete(key);
             // A dispose that rejects is still a settled close: nothing remains to wait for.
             const tracked = closed.then(() => undefined, () => undefined).then(() => {
-                if (this.closing.get(sessionId) === tracked)
-                    this.closing.delete(sessionId);
+                if (this.closing.get(key) === tracked)
+                    this.closing.delete(key);
             });
-            this.closing.set(sessionId, tracked);
+            this.closing.set(key, tracked);
         });
-        this.sessions.set(sessionId, feed);
+        this.sessions.set(key, feed);
         return feed;
     }
 }

package/lib/types/client/provider.d.ts

@@ -13,9 +13,9 @@
  * a string outside the grammar, `workspace-file/unknown-workspace` when the
  * address carries no Session — and ends.
  *
- * The first frame is the file's `stat`; every Host-reported write yields the
- * metadata with its reported version; a reported disappearance, or a write while the
- * last stat had failed, runs `stat` again. Failures travel as `ok: false` frames, never as thrown errors: the
+ * The first frame is the file's `stat`; subsequent invalidations run `stat`
+ * again unless their version or absence is already known. Reconnection also
+ * restats the file. Failures travel as `ok: false` frames, never as thrown errors: the
  * Remote face does not reject, and anything thrown inside the stream is a
  * programming error the resource model lets surface. A failed stat does not end
  * the stream: the next write stats again. One {@link ChangeFeed}
@@ -27,7 +27,7 @@ import type { WorkspaceFilesRemote } from './remote.ts';
 /**
  * Build the `file` provider over one Remote face and one change feed.
  * @param remote - the Remote face carrying `workspaceFiles.stat`.
- * @param changes - the per-session change fan-out.
+ * @param changes - target-scoped change streams shared by file resources.
  * @returns the provider to register into `ctx.resources`.
  */
 export declare function createFileResourceProvider(remote: WorkspaceFilesRemote, changes: ChangeFeed): ResourceProvider<'file'>;

package/lib/types/client/provider.js

@@ -3,7 +3,7 @@ import { parseFileAddress } from '@deepseek-ai/dsh-util-workspace-path';
 /**
  * Build the `file` provider over one Remote face and one change feed.
  * @param remote - the Remote face carrying `workspaceFiles.stat`.
- * @param changes - the per-session change fan-out.
+ * @param changes - target-scoped change streams shared by file resources.
  * @returns the provider to register into `ctx.resources`.
  */
 export function createFileResourceProvider(remote, changes) {
@@ -17,7 +17,7 @@ export function createFileResourceProvider(remote, changes) {
             }
             const { sessionId, path } = resolved.value;
             // Queue changes delivered to this Client while stat is pending.
-            const notices = changes.follow(sessionId, signal);
+            const notices = changes.follow(sessionId, path, signal);
             const stat = () => remote.workspaceFiles.stat(sessionId, path, signal);
             // Read through a call: a plain `signal.aborted` is narrowed to `false` by
             // the first check and would read as always-false after the later awaits.
@@ -26,7 +26,15 @@ export function createFileResourceProvider(remote, changes) {
             // on the file, so a write can still bring the file live.
             let current;
             try {
-                if (!await notices.ready || aborted())
+                if (!await notices.ready) {
+                    if (aborted())
+                        return;
+                    const result = await stat();
+                    if (!aborted())
+                        yield result;
+                    return;
+                }
+                if (aborted())
                     return;
                 const first = await stat();
                 if (aborted())
@@ -40,6 +48,8 @@ export function createFileResourceProvider(remote, changes) {
                     yield first;
                 }
                 for await (const notice of notices) {
+                    if (aborted())
+                        return;
                     if (current === undefined) {
                         // Still gone: nothing new to report.
                         if (notice.kind === 'absent')
@@ -50,9 +60,6 @@ export function createFileResourceProvider(remote, changes) {
                         // consumer learns nothing new.
                         if (notice.version === current.version)
                             continue;
-                        current = { ...current, version: notice.version };
-                        yield { ok: true, value: current };
-                        continue;
                     }
                     // A Host notice may mean stale content.
                     const again = await stat();

package/lib/types/client/types.d.ts

@@ -34,13 +34,15 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
         };
     }
 }
-/** One Host-reported write inside the session's workspace. */
+/** One Host-reported target change in the Session's filesystem. */
 export type WorkspaceFileEdit = {
     readonly kind: 'changed';
     readonly version: string;
 } | {
     readonly kind: 'absent';
 };
-/** What one follower of a path receives: a Host write. */
-export type WorkspaceFileNotice = WorkspaceFileEdit;
+/** A target change or a request to restat after reconnection. */
+export type WorkspaceFileNotice = WorkspaceFileEdit | {
+    readonly kind: 'refresh';
+};
 //# sourceMappingURL=types.d.ts.map

package/lib/types/index.d.ts

@@ -22,7 +22,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import { TypertRemoteService, type TypertLookup } from '@deepseek-ai/dsh-typert-protocol';
-import type { WorkspaceByteRange, WorkspaceDirectoryListing, WorkspaceFileBytes, WorkspaceFileRange, WorkspaceFileStat, WorkspaceFileText, WorkspaceFileWatchFrame } from './types.ts';
+import type { WorkspaceByteReadOptions, WorkspaceDirectoryListing, WorkspaceFileBytes, WorkspaceFileRange, WorkspaceFileStat, WorkspaceFileText, WorkspaceFileWatchFrame } from './types.ts';
 export type * from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -81,32 +81,14 @@ export declare class WorkspaceFiles extends TypertRemoteService {
      */
     read(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>;
     /**
-     * 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.
-     */
-    readBytes(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>;
-    /**
-     * 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.
-     */
-    readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileBytes>;
-    /**
-     * 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 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 the complete related file using the ordinary file-size and access checks.
+     * @returns native bytes with the file's version and size at the preceding stat, byte offset, and EOF marker.
      */
-    readRelated(workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal): Promise<WorkspaceFileBytes>;
+    readBytes(workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal): Promise<WorkspaceFileBytes>;
     /**
      * Report one regular file's identity, version, and size without its content.
      * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
@@ -124,15 +106,16 @@ export declare class WorkspaceFiles extends TypertRemoteService {
      */
     list(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>;
     /**
-     * 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: WorkspaceFileScope, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>;
+    changes(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>;
+    private relativePath;
     /** Apply the page defaults and caps here, so the request never carries them implicitly. */
     private resolvePage;
     /** Apply the byte-window defaults and cap; a window above the cap is refused, not shortened. */