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

package/lib/types/client/provider.js

@@ -1,30 +1,29 @@
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
 import { parseFileAddress } from '@deepseek-ai/dsh-util-workspace-path';
 /**
- * Build the `file` provider over one Remote face, one change feed, and the Client's Session list.
+ * 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 sessions - the current Session, read for absolute addresses on every open and reload.
  * @returns the provider to register into `ctx.resources`.
  */
-export function createFileResourceProvider(remote, changes, sessions) {
+export function createFileResourceProvider(remote, changes) {
     return {
         protocol: 'file',
         async *open(address, { signal }) {
-            const resolved = resolve(address, sessions);
+            const resolved = resolve(address);
             if (!resolved.ok) {
                 yield resolved;
                 return;
             }
             const { sessionId, path } = resolved.value;
             // Queue changes delivered to this Client while stat is pending.
-            const notices = changes.follow(sessionId, address, signal);
+            const notices = changes.follow(sessionId, 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.
             const aborted = () => signal.aborted;
             // Undefined while the last stat failed: the follow is on the address, not
-            // on the file, so a write or a reload can still bring the file live.
+            // on the file, so a write can still bring the file live.
             let current;
             try {
                 if (!await notices.ready || aborted())
@@ -34,7 +33,7 @@ export function createFileResourceProvider(remote, changes, sessions) {
                     return;
                 if (first.ok) {
                     notices.bind(first.value.absolutePath);
-                    current = metadataOf(first.value, false);
+                    current = first.value;
                     yield { ok: true, value: current };
                 }
                 else {
@@ -51,11 +50,11 @@ export function createFileResourceProvider(remote, changes, sessions) {
                         // consumer learns nothing new.
                         if (notice.version === current.version)
                             continue;
-                        current = { ...current, version: notice.version, changed: true };
+                        current = { ...current, version: notice.version };
                         yield { ok: true, value: current };
                         continue;
                     }
-                    // A Host notice may mean stale content; only a reload clears the flag.
+                    // A Host notice may mean stale content.
                     const again = await stat();
                     if (aborted())
                         return;
@@ -65,7 +64,7 @@ export function createFileResourceProvider(remote, changes, sessions) {
                         continue;
                     }
                     notices.bind(again.value.absolutePath);
-                    current = metadataOf(again.value, notice.kind !== 'restat');
+                    current = again.value;
                     yield { ok: true, value: current };
                 }
             }
@@ -73,20 +72,14 @@ export function createFileResourceProvider(remote, changes, sessions) {
                 notices.dispose();
             }
         },
-        reload(address) {
-            const resolved = resolve(address, sessions);
-            if (resolved.ok)
-                changes.requestRestat(resolved.value.sessionId, address);
-        },
     };
 }
 /**
  * Resolve one address to the Host call it stands for, or to the failure frame it earns.
  * @param address - the full address, scheme included.
- * @param sessions - the Client's Session list.
  * @returns the Host file, or the `unsupported-address` / `unknown-workspace` failure.
  */
-function resolve(address, sessions) {
+function resolve(address) {
     const parsed = parseFileAddress(address);
     if (parsed === undefined)
         return { ok: false, error: unsupportedAddress(address) };
@@ -95,10 +88,7 @@ function resolve(address, sessions) {
         const sessionId = parsed.sessionId;
         return { ok: true, value: { sessionId, path: parsed.path } };
     }
-    const sessionId = sessions.current();
-    if (sessionId === undefined)
-        return { ok: false, error: unknownWorkspace(address) };
-    return { ok: true, value: { sessionId, path: parsed.path } };
+    return { ok: false, error: unknownWorkspace(address) };
 }
 /**
  * The failure frame's error for an address this provider does not serve.
@@ -109,21 +99,11 @@ function unsupportedAddress(address) {
     return new RemoteError('workspace-file/unsupported-address', `${address} is not a dsh-resource://file/session/<sessionId>/<path> or dsh-resource://file/absolute/<path> address`, { address });
 }
 /**
- * The failure frame's error for an absolute address with no current Session.
+ * The failure frame's error for an absolute address with no Session.
  * @param address - the offending address.
  * @returns the typed error.
  */
 function unknownWorkspace(address) {
-    return new RemoteError('workspace-file/unknown-workspace', `${address} requires a current Session`, { address });
-}
-/**
- * The resource value one `stat` result amounts to.
- * @param stat - what the Host reported.
- * @param changed - whether the consumer's content may be stale: `true` after a
- *   Host notice prompted the stat, `false` for the opening stat and a reload's.
- * @returns the metadata frame value.
- */
-function metadataOf(stat, changed) {
-    return { absolutePath: stat.absolutePath, version: stat.version, changed, ...(stat.bytes === undefined ? {} : { bytes: stat.bytes }) };
+    return new RemoteError('workspace-file/unknown-workspace', `${address} requires a dsh-resource://file/session/<sessionId>/<path> address`, { address });
 }
 //# sourceMappingURL=provider.js.map

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

@@ -1,11 +1,11 @@
+import type { WorkspaceFileStat } from '../types.ts';
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface ResourceProtocolMap {
         /**
          * One workspace file's metadata, addressed as
-         * `dsh-resource://file/session/<sessionId>/<workspace-relative path>` or
-         * `dsh-resource://file/absolute/<absolute path>`.
+         * `dsh-resource://file/session/<sessionId>/<path>` (absolute or workspace-relative).
          */
-        file: WorkspaceFileResource;
+        file: WorkspaceFileStat;
     }
 }
 /** What a `file` tab is asked to reveal on open or navigation; JSON-shaped. */
@@ -17,7 +17,7 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
     interface RemoteErrorDetailsMap {
         /**
          * The address is not a `dsh-resource://file/` address in a scope the
-         * provider serves: `session/<sessionId>/<workspace-relative path>` or
+         * provider recognizes: `session/<sessionId>/<path>` or
          * `absolute/<absolute path>`. Raised by the Client provider; the Host never
          * emits it.
          */
@@ -25,7 +25,7 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
             readonly address: string;
         };
         /**
-         * An `absolute` address has no current Session to authorize its Host call.
+         * An `absolute` address has no Session to authorize its Host call.
          * Raised by the Client provider; the Host never emits it. Session addresses
          * are resolved by the Host without a Client Session summary.
          */
@@ -34,23 +34,6 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
         };
     }
 }
-/**
- * One workspace file as the resource model carries it: metadata only.
- *
- * The stream reports that the file moved on; it never carries content. A
- * consumer reads the text itself, by page, and uses `version` and `changed` to
- * know when its pages are stale.
- */
-export interface WorkspaceFileResource {
-    /** Absolute path in the Host filesystem, as returned by the last successful stat. */
-    readonly absolutePath: string;
-    /** The Host's latest report of the file's version: from `stat` first, then from each reported write. */
-    readonly version: string;
-    /** Byte size as of the last `stat`, when the backend reports it. */
-    readonly bytes?: number;
-    /** The Host reported a write after the last `stat`; a reload (`stat` again) clears it. */
-    readonly changed: boolean;
-}
 /** One Host-reported write inside the session's workspace. */
 export type WorkspaceFileEdit = {
     readonly kind: 'changed';
@@ -58,8 +41,6 @@ export type WorkspaceFileEdit = {
 } | {
     readonly kind: 'absent';
 };
-/** What one follower of a path receives: a Host write, or a local request to `stat` again. */
-export type WorkspaceFileNotice = WorkspaceFileEdit | {
-    readonly kind: 'restat';
-};
+/** What one follower of a path receives: a Host write. */
+export type WorkspaceFileNotice = WorkspaceFileEdit;
 //# sourceMappingURL=types.d.ts.map

package/lib/types/index.d.ts

@@ -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
@@ -26,8 +20,8 @@
  */
 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 { 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';
 export type * from './types.ts';
 declare module '@deepseek-ai/cordis' {
@@ -36,6 +30,19 @@ declare module '@deepseek-ai/cordis' {
         workspaceFiles: WorkspaceFiles;
     }
 }
+/** Header-derived file resolution context for one Session identity. */
+export interface WorkspaceFileScope {
+    /** Session identity received on the wire. */
+    readonly sessionId: SessionId;
+    /** Session workspace root, or the deployment fallback when its header has no cwd. */
+    readonly workspaceRoot: string;
+}
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface TypertLookupMap {
+        /** Resolve a Session id to its workspace root without loading its event body or activating an Agent. */
+        workspaceFileScope: TypertLookup<WorkspaceFileScope, SessionId>;
+    }
+}
 /** Deployment caps on one page or one listing. */
 export interface Config {
     /**
@@ -46,12 +53,14 @@ export interface Config {
      * way. The file itself has no size cap: a caller pages through it.
      */
     readonly maxBytes: number;
+    /** Inclusive byte cap on a complete-file read; larger files are refused, never truncated. */
+    readonly maxFileBytes: 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. */
+/** Host Remote file reads and workspace directory observations over the composed filesystem. */
 export declare class WorkspaceFiles extends TypertRemoteService {
     private readonly config;
     static inject: string[];
@@ -63,68 +72,74 @@ export declare class WorkspaceFiles extends TypertRemoteService {
      */
     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.
+     * 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.
      */
-    read(agent: Agent, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>;
+    read(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>;
     /**
-     * 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.
      */
-    readBytes(agent: Agent, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>;
+    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 signal - caller cancellation.
+     * @returns the complete related file using the ordinary file-size and access checks.
+     */
+    readRelated(workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, 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 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.
      */
-    stat(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>;
+    stat(workspaceFileScope: WorkspaceFileScope, 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.
+     * 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.
      */
-    list(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>;
+    list(workspaceFileScope: WorkspaceFileScope, 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.
+     * 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: Agent, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>;
+    changes(workspaceFileScope: WorkspaceFileScope, 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.
+     * Inspect the requested path itself before resolution follows its final
+     * component. Directory containment is checked separately by `list`.
      */
     private inspect;
     /** Resolve an inspected path and refuse it unless the workspace contains it. */