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

package/lib/types/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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.
+ *
+ * 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`.
+ *
+ * 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
+ * never held whole in memory; the NUL scan runs on the page itself.
+ *
+ * This is NOT modelled on `session.openWorkspacePath`. That endpoint hands a
+ * path to the local opener and leaves the effect on the machine; this one sends
+ * file content across the wire, which is a different level of exposure.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { WorkspaceByteRange, WorkspaceDirectoryListing, WorkspaceFileBytes, WorkspaceFileRange, WorkspaceFileStat, WorkspaceFileText, WorkspaceFileWatchFrame } from './types.ts';
+export type * from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Host owner of the `workspaceFiles` Remote namespace. */
+        workspaceFiles: WorkspaceFiles;
+    }
+}
+/** Deployment caps on one page or one listing. */
+export interface Config {
+    /**
+     * Inclusive byte cap on one page's text and on one byte window.
+     *
+     * A page above this fails; it is not shortened, because a silently cut page
+     * reads as the whole page. A byte window asking for more is refused the same
+     * way. The file itself has no size cap: a caller pages through it.
+     */
+    readonly maxBytes: number;
+    /** Default and largest page size in lines; a request asking for more is refused. */
+    readonly maxLines: number;
+    /** Cap on returned directory entries; the rest is dropped and reported cut. */
+    readonly maxEntries: number;
+}
+/** Host Remote service over the composed filesystem, confined to one workspace. */
+export declare class WorkspaceFiles extends TypertRemoteService {
+    private readonly config;
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly feed;
+    /**
+     * @param ctx - Host context carrying the filesystem and the sandbox policy.
+     * @param config - deployment caps on one page or one listing.
+     */
+    constructor(ctx: Context, config: Config);
+    /**
+     * 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.
+     * @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.
+     */
+    read(agent: Agent, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>;
+    /**
+     * Read one byte window of a regular file inside the Agent's workspace: 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 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(agent: Agent, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>;
+    /**
+     * 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 signal - caller cancellation.
+     * @returns the file's absolute path, current version, and byte size.
+     */
+    stat(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>;
+    /**
+     * List the direct children of one directory 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.
+     * @param signal - caller cancellation.
+     * @returns the directory's children in the backend's stable name order, bounded by the entry cap.
+     */
+    list(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>;
+    /**
+     * 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.
+     * @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: Agent, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>;
+    /** 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. */
+    private resolveWindow;
+    /**
+     * 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.
+     */
+    private workspaceRootOf;
+    /**
+     * 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.
+     */
+    private inspect;
+    /** Resolve an inspected path and refuse it unless the workspace contains it. */
+    private confine;
+    /**
+     * All gates for a regular file, ending in the one stat that names its version
+     * and size. The stat re-checks what `lstat` saw: the file may have gone or
+     * changed kind in between.
+     */
+    private locateFile;
+    private statOf;
+    /** Stream the file as text and cut the page, classifying the backend's non-text refusal. */
+    private cutPage;
+}
+export default WorkspaceFiles;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,368 @@
+/**
+ * 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.
+ *
+ * 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`.
+ *
+ * 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
+ * never held whole in memory; the NUL scan runs on the page itself.
+ *
+ * This is NOT modelled on `session.openWorkspacePath`. That endpoint hands a
+ * path to the local opener and leaves the effect on the machine; this one sends
+ * file content across the wire, which is a different level of exposure.
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import z from '@deepseek-ai/schemastery';
+import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { WorkspaceChangeFeed } from "./changes.js";
+/** The byte text never carries: its presence marks a page as binary. */
+const NUL = String.fromCharCode(0);
+/** Refuse anything the wire schema admits as a number but a window cannot use: only safe integers index a file. */
+function integerAtLeast(value, min, name) {
+    if (!Number.isSafeInteger(value) || value < min) {
+        throw new RemoteError('gateway/bad-request', `${name} must be a safe integer of at least ${min}`, {});
+    }
+    return value;
+}
+/**
+ * Cut lines `offset` through `offset + limit - 1` from decoded chunks, stopping
+ * at the first character past the page so the rest of the file is never read.
+ * Lines before the page are counted, not kept, and the page is refused the
+ * moment its bytes exceed `maxBytes`, so one giant line cannot grow memory past
+ * the cap either.
+ */
+async function cutPage(chunks, offset, limit, maxBytes, path) {
+    const last = offset + limit - 1;
+    const lines = [];
+    let current = '';
+    let bytes = 0;
+    let lineNumber = 1;
+    const admit = (size) => {
+        bytes += size;
+        if (bytes > maxBytes) {
+            throw new RemoteError('workspace-file/too-large', `lines ${offset}-${last} of "${path}" exceed the ${maxBytes} byte cap`, { path, limit: maxBytes });
+        }
+    };
+    const complete = () => {
+        if (lines.length > 0)
+            admit(1);
+        lines.push(current);
+        current = '';
+    };
+    for await (const chunk of chunks) {
+        let position = 0;
+        while (position < chunk.length) {
+            if (lineNumber > last)
+                return { text: lines.join('\n'), lines: lines.length, eof: false };
+            const newline = chunk.indexOf('\n', position);
+            const segment = newline === -1 ? chunk.slice(position) : chunk.slice(position, newline);
+            if (lineNumber >= offset) {
+                admit(Buffer.byteLength(segment, 'utf8'));
+                current += segment;
+            }
+            if (newline === -1)
+                break;
+            if (lineNumber >= offset)
+                complete();
+            lineNumber += 1;
+            position = newline + 1;
+        }
+    }
+    // Only an in-page line can be pending here: earlier lines were never kept,
+    // and a character past the page returned above.
+    if (current.length > 0)
+        complete();
+    return { text: lines.join('\n'), lines: lines.length, eof: true };
+}
+/**
+ * Workspace path of `target` relative to `root`, derived from the two canonical
+ * `file:` URIs so the answer is `/`-joined on every platform. Empty for the root.
+ */
+function workspacePathOf(rootUrl, targetUrl) {
+    const root = new URL(rootUrl).pathname.replace(/\/+$/, '');
+    const target = new URL(targetUrl).pathname;
+    if (target === root)
+        return '';
+    return target.slice(root.length + 1).split('/').map(decodeURIComponent).join('/');
+}
+/** Strip the resolved child target: the wire carries names and metadata only. */
+function directoryEntry(child) {
+    return {
+        name: child.name,
+        type: child.type,
+        ...child.size === undefined ? {} : { size: child.size },
+    };
+}
+/** Host Remote service over the composed filesystem, confined to one workspace. */
+let WorkspaceFiles = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _read_decorators;
+    let _readBytes_decorators;
+    let _stat_decorators;
+    let _list_decorators;
+    let _changes_decorators;
+    return class WorkspaceFiles extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _read_decorators = [Remote];
+            _readBytes_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, _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 Config = z.object({
+            maxBytes: z.number().step(1).min(1).default(2 * 1024 * 1024),
+            maxLines: z.number().step(1).min(1).default(5000),
+            maxEntries: z.number().step(1).min(1).default(2000),
+        });
+        feed;
+        /**
+         * @param ctx - Host context carrying the filesystem and the sandbox policy.
+         * @param config - deployment caps on one page or one listing.
+         */
+        constructor(ctx, config) {
+            super(ctx, 'workspaceFiles');
+            this.config = config;
+            this.feed = new WorkspaceChangeFeed(ctx);
+        }
+        /**
+         * 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.
+         * @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) {
+            const { offset, limit } = this.resolvePage(range);
+            const { target, info } = await this.locateFile(agent, 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 { ...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
+         * 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 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) {
+            const { offset, length } = this.resolveWindow(range, path);
+            const { target, info } = await this.locateFile(agent, 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 };
+        }
+        /**
+         * 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 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);
+            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.
+         * @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);
+            if (entry.type !== 'directory') {
+                throw new RemoteError('workspace-file/not-directory', `"${path}" is a ${entry.type}`, { path, kind: entry.type });
+            }
+            const target = await this.confine(root, workspaceRoot, path, signal);
+            const children = await this.ctx.fs.listDir(target, signal);
+            return {
+                path: workspacePathOf(this.ctx.fs.fileUrl(root), this.ctx.fs.fileUrl(target)),
+                entries: children.slice(0, this.config.maxEntries).map(directoryEntry),
+                truncated: children.length > this.config.maxEntries,
+            };
+        }
+        /**
+         * 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.
+         * @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);
+        }
+        /** Apply the page defaults and caps here, so the request never carries them implicitly. */
+        resolvePage(range) {
+            const offset = range.offset === undefined ? 1 : integerAtLeast(range.offset, 1, 'offset');
+            const limit = range.limit === undefined ? this.config.maxLines : integerAtLeast(range.limit, 1, 'limit');
+            if (limit > this.config.maxLines) {
+                throw new RemoteError('gateway/bad-request', `limit must be at most ${this.config.maxLines}`, {});
+            }
+            return { offset, limit };
+        }
+        /** Apply the byte-window defaults and cap; a window above the cap is refused, not shortened. */
+        resolveWindow(range, path) {
+            const offset = range.offset === undefined ? 0 : integerAtLeast(range.offset, 0, 'offset');
+            const length = range.length === undefined ? this.config.maxBytes : integerAtLeast(range.length, 1, 'length');
+            if (offset + length > Number.MAX_SAFE_INTEGER) {
+                throw new RemoteError('gateway/bad-request', 'offset plus length must stay a safe integer', {});
+            }
+            if (length > this.config.maxBytes) {
+                throw new RemoteError('workspace-file/too-large', `${length} bytes of "${path}" exceed the ${this.config.maxBytes} byte cap`, { path, limit: this.config.maxBytes });
+            }
+            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.
+         */
+        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) {
+            if (path.length === 0)
+                throw new RemoteError('gateway/bad-request', 'path is required', {});
+            const workspaceRoot = this.workspaceRootOf(agent);
+            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);
+            if (entry === undefined) {
+                throw new RemoteError('workspace-file/not-found', `no entry at "${path}"`, { path });
+            }
+            return { root, workspaceRoot, entry };
+        }
+        /** Resolve an inspected path and refuse it unless the workspace contains it. */
+        async confine(root, workspaceRoot, path, signal) {
+            const target = await this.ctx.fs.resolve(path, { cwd: workspaceRoot, signal });
+            if (!this.ctx.fs.contains(root, target)) {
+                throw new RemoteError('workspace-file/outside-workspace', `"${path}" is outside the workspace`, { path });
+            }
+            return target;
+        }
+        /**
+         * All gates for a regular file, ending in the one stat that names its version
+         * 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);
+            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 info = await this.ctx.fs.stat(target, signal);
+            if (info === undefined) {
+                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}`, { path, kind: info.type });
+            }
+            return { target, info };
+        }
+        statOf(target, info) {
+            return {
+                absolutePath: this.ctx.fs.processPath(target),
+                version: info.version,
+                ...info.size === undefined ? {} : { bytes: info.size },
+            };
+        }
+        /** Stream the file as text and cut the page, classifying the backend's non-text refusal. */
+        async cutPage(target, offset, limit, signal, path) {
+            try {
+                return await cutPage(await this.ctx.fs.streamText(target, signal), offset, limit, this.config.maxBytes, path);
+            }
+            catch (error) {
+                if (isNotTextRefusal(error)) {
+                    throw new RemoteError('workspace-file/not-text', `"${path}" is not UTF-8 text`, { path }, { cause: error });
+                }
+                throw error;
+            }
+        }
+    };
+})();
+export { WorkspaceFiles };
+/**
+ * The backend's non-text refusal, recognized by its code alone: the error class
+ * belongs to whichever `dsh-fs` instance the provider loaded, so no class
+ * identity is shared across the package boundary.
+ */
+function isNotTextRefusal(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'FS_NOT_TEXT';
+}
+export default WorkspaceFiles;
+//# sourceMappingURL=index.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Wire types of the `workspaceFiles` Remote namespace. Types only: generated
+ * Remote clients consume this module without Host runtime code.
+ *
+ * Two path vocabularies leave here, and each method uses exactly one:
+ *
+ * - `read`, `readBytes`, `stat`, and `changes` name a file by its absolute path in the
+ *   filesystem's execution world, because their consumer is the Client
+ *   resource system, whose `dsh-resource://file/session/<id>/<path>` address carries that
+ *   same path.
+ * - `list` speaks workspace paths — the same syntax its `path` argument accepts —
+ *   because its consumer is a tree rooted at the workspace root.
+ *
+ * @module @deepseek-ai/dsh-api-workspace-files/types
+ */
+/** Identity and freshness of one workspace file, without its content. */
+export interface WorkspaceFileStat {
+    /**
+     * Absolute path of the file in the filesystem's execution world, symlinks
+     * resolved: `/`-separated on POSIX, drive-rooted with the platform separator
+     * on Windows. What a `dsh-resource://file/absolute/…` address carries, and
+     * what a `dsh-resource://file/session/<sessionId>/…` address's
+     * workspace-relative path resolves to against that Session's root.
+     */
+    readonly absolutePath: string;
+    /** Opaque freshness token at the time of the stat; never parsed. */
+    readonly version: string;
+    /** Byte size of the complete file, when the backend reports it. */
+    readonly bytes?: number;
+}
+/**
+ * The line window one `read` returns. Lines are 1-based and end at `\n`; a
+ * final `\n` terminates the last line rather than starting an empty one.
+ */
+export interface WorkspaceFileRange {
+    /** First line of the page. Defaults to 1. */
+    readonly offset?: number;
+    /** Largest number of lines on the page. Defaults to, and may not exceed, the configured `maxLines`. */
+    readonly limit?: number;
+}
+/** One page of a workspace text file as a Client reads it. */
+export interface WorkspaceFileText extends WorkspaceFileStat {
+    /** First line of the page, as requested. */
+    readonly offset: number;
+    /**
+     * The page's lines joined by `\n`, without a terminator after the last one.
+     * Empty for a page past the file's last line and for a page holding one
+     * empty line; `lines` tells them apart.
+     */
+    readonly text: string;
+    /** How many lines the page holds; `0` when `offset` lies past the file's last line. */
+    readonly lines: number;
+    /** Whether the page includes the file's last line. */
+    readonly eof: boolean;
+}
+/** The byte window one `readBytes` returns. Offsets are 0-based. */
+export interface WorkspaceByteRange {
+    /** First byte of the window. Defaults to 0. */
+    readonly offset?: number;
+    /** Largest number of bytes in the window. Defaults to, and may not exceed, the configured `maxBytes`. */
+    readonly length?: number;
+}
+/**
+ * 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 {
+    /** 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;
+    /** Whether the window includes the file's last byte. */
+    readonly eof: boolean;
+}
+/** One direct child of a listed workspace directory. */
+export interface WorkspaceDirectoryEntry {
+    /** Basename inside the listed directory. */
+    readonly name: string;
+    /**
+     * What the child resolves to. A symlink reports the type of its destination,
+     * and `other` covers everything that is neither a regular file nor a
+     * directory; `read` still refuses a symlink, so `file` here is a listing fact,
+     * not a promise that the content is readable.
+     */
+    readonly type: 'file' | 'directory' | 'other';
+    /** Byte size, present only for a regular file whose backend reports it. */
+    readonly size?: number;
+}
+/** Direct children of one workspace directory. */
+export interface WorkspaceDirectoryListing {
+    /**
+     * The listed directory as a workspace path, relative to the workspace root
+     * and empty for the root itself. A child's path is this value joined with
+     * {@link WorkspaceDirectoryEntry.name} by `/`.
+     */
+    readonly path: string;
+    /**
+     * Direct children in the backend's stable name order, cut to the configured
+     * entry cap. Presentation order is the caller's choice.
+     */
+    readonly entries: readonly WorkspaceDirectoryEntry[];
+    /** Whether the entry cap dropped children from {@link entries}. */
+    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.
+ */
+export type WorkspaceFileChange = {
+    /** Absolute path of the observed file, in the same form as {@link WorkspaceFileStat.absolutePath}. */
+    readonly absolutePath: string;
+    /** Opaque freshness token after the observed operation; never parsed. */
+    readonly version: string;
+} | {
+    /** Absolute path of the observed file, in the same form as {@link WorkspaceFileStat.absolutePath}. */
+    readonly absolutePath: string;
+    /** The file 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.
+ */
+export type WorkspaceFileWatchFrame = {
+    readonly kind: 'ready';
+} | {
+    readonly kind: 'change';
+    readonly change: WorkspaceFileChange;
+};
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        /** No entry exists at that path inside the workspace. */
+        'workspace-file/not-found': {
+            readonly path: string;
+        };
+        /** The path resolves outside the session's workspace root. */
+        'workspace-file/outside-workspace': {
+            readonly path: string;
+        };
+        /** The requested page exceeds the configured byte cap; nothing is returned. */
+        'workspace-file/too-large': {
+            readonly path: string;
+            readonly limit: number;
+        };
+        /** The content read so far is not decodable UTF-8 text, or the page carries NUL bytes. */
+        'workspace-file/not-text': {
+            readonly path: string;
+        };
+        /** The path is not a regular file, so it has no text to read. */
+        'workspace-file/not-regular-file': {
+            readonly path: string;
+            readonly kind: 'directory' | 'symlink' | 'other';
+        };
+        /** The path is not a directory, so it has no children to list. */
+        'workspace-file/not-directory': {
+            readonly path: string;
+            readonly kind: 'file' | 'symlink' | 'other';
+        };
+    }
+}
+//# sourceMappingURL=types.d.ts.map