disk 0.8.10 → 0.8.12

package/dist/cli.js

@@ -223,6 +223,31 @@ var Disk = class {
       })
     );
   }
+  /**
+   * Constant-time parallel grep across files on this disk. Listing and
+   * matching are fanned out across ephemeral exec containers; the request
+   * finishes within the supplied time budget regardless of dataset size.
+   *
+   * The returned `stoppedReason` says whether the search ran to completion
+   * or short-circuited on `maxResults` / `maxDurationSeconds`. When
+   * stopping early, the matches returned are a sample (whichever workers
+   * reported first), not the lexicographically first N.
+   */
+  async grep(opts) {
+    return unwrap(
+      this._client.POST("/api/disks/{id}/grep", {
+        params: { path: { id: this.id } },
+        body: {
+          directory: opts.directory,
+          pattern: opts.pattern,
+          recursive: opts.recursive ?? false,
+          maxDurationSeconds: opts.maxDurationSeconds ?? 30,
+          concurrency: opts.concurrency ?? 50,
+          maxResults: opts.maxResults ?? 1e3
+        }
+      })
+    );
+  }
   /**
    * Connect to this disk's data plane via the native ArchilClient.
    *
@@ -338,6 +363,12 @@ var Tokens = class {
 };
 
 // src/archil.ts
+function isExecMountSpec(m) {
+  return typeof m === "object" && m !== null && "disk" in m;
+}
+function diskIdFromMount(m) {
+  return typeof m === "string" ? m : m.id;
+}
 var Archil = class {
   disks;
   tokens;
@@ -369,7 +400,16 @@ var Archil = class {
   async exec(opts) {
     const disks = {};
     for (const [relPath, mount] of Object.entries(opts.disks)) {
-      disks[relPath] = typeof mount === "string" ? mount : mount.id;
+      if (isExecMountSpec(mount)) {
+        const entry = {
+          disk: diskIdFromMount(mount.disk),
+          readOnly: mount.readOnly ?? false
+        };
+        if (mount.subdirectory !== void 0) entry.subdirectory = mount.subdirectory;
+        disks[relPath] = entry;
+      } else {
+        disks[relPath] = diskIdFromMount(mount);
+      }
     }
     return unwrap(
       this._client.POST("/api/exec", {

package/dist/index.cjs

@@ -266,6 +266,31 @@ var Disk = class {
       })
     );
   }
+  /**
+   * Constant-time parallel grep across files on this disk. Listing and
+   * matching are fanned out across ephemeral exec containers; the request
+   * finishes within the supplied time budget regardless of dataset size.
+   *
+   * The returned `stoppedReason` says whether the search ran to completion
+   * or short-circuited on `maxResults` / `maxDurationSeconds`. When
+   * stopping early, the matches returned are a sample (whichever workers
+   * reported first), not the lexicographically first N.
+   */
+  async grep(opts) {
+    return unwrap(
+      this._client.POST("/api/disks/{id}/grep", {
+        params: { path: { id: this.id } },
+        body: {
+          directory: opts.directory,
+          pattern: opts.pattern,
+          recursive: opts.recursive ?? false,
+          maxDurationSeconds: opts.maxDurationSeconds ?? 30,
+          concurrency: opts.concurrency ?? 50,
+          maxResults: opts.maxResults ?? 1e3
+        }
+      })
+    );
+  }
   /**
    * Connect to this disk's data plane via the native ArchilClient.
    *
@@ -381,6 +406,12 @@ var Tokens = class {
 };
 
 // src/archil.ts
+function isExecMountSpec(m) {
+  return typeof m === "object" && m !== null && "disk" in m;
+}
+function diskIdFromMount(m) {
+  return typeof m === "string" ? m : m.id;
+}
 var Archil = class {
   disks;
   tokens;
@@ -412,7 +443,16 @@ var Archil = class {
   async exec(opts) {
     const disks = {};
     for (const [relPath, mount] of Object.entries(opts.disks)) {
-      disks[relPath] = typeof mount === "string" ? mount : mount.id;
+      if (isExecMountSpec(mount)) {
+        const entry = {
+          disk: diskIdFromMount(mount.disk),
+          readOnly: mount.readOnly ?? false
+        };
+        if (mount.subdirectory !== void 0) entry.subdirectory = mount.subdirectory;
+        disks[relPath] = entry;
+      } else {
+        disks[relPath] = diskIdFromMount(mount);
+      }
     }
     return unwrap(
       this._client.POST("/api/exec", {

package/dist/index.d.cts

@@ -148,6 +148,48 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/disks/{id}/grep": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Constant-time parallel grep over a directory on a disk
+         * @description Searches files under a directory on the disk for lines matching a
+         *     regular expression. Listing and matching are fanned out across
+         *     ephemeral exec containers, so the request finishes within the user's
+         *     time budget regardless of the size of the directory.
+         *
+         *     The user controls cost and latency with three knobs:
+         *
+         *     - `maxDurationSeconds` is the wall-clock deadline.
+         *     - `concurrency` is the maximum number of parallel grep workers.
+         *       Higher concurrency finishes larger datasets within the deadline;
+         *       the controlplane clamps to the runtime fleet's current capacity.
+         *     - `maxResults` causes the search to short-circuit after the
+         *       aggregator has collected this many matches.
+         *
+         *     With `recursive: false` only files directly under `directory` are
+         *     searched. With `recursive: true` subdirectories are walked
+         *     breadth-first and grep workers are dispatched as soon as each level
+         *     finishes listing — listing and matching overlap.
+         *
+         *     The matches returned when stopping early on `maxResults` are a sample
+         *     of whichever workers reported first, not the lexicographically first
+         *     N. The response surfaces `stoppedReason` so callers can distinguish
+         *     completion from early termination.
+         */
+        post: operations["grepDisk"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/exec": {
         parameters: {
             query?: never;
@@ -711,13 +753,21 @@ interface components {
              * @description Map of relative path under `/mnt/archil` to the disk to mount
              *     there. At least one entry is required. Relative paths must be
              *     non-empty, non-absolute, and contain no `.` or `..` segments.
+             *
+             *     Each value is either a plain disk ID string (mounts the disk's
+             *     root, read-write) or an object that additionally selects a
+             *     subdirectory of the disk and/or marks the mount as read-only.
              * @example {
              *       "data": "dsk-abc123",
-             *       "logs": "dsk-def456"
+             *       "logs": {
+             *         "disk": "dsk-def456",
+             *         "subdirectory": "app/logs",
+             *         "readOnly": true
+             *       }
              *     }
              */
             disks: {
-                [key: string]: string;
+                [key: string]: string | components["schemas"]["ExecMount"];
             };
             /**
              * @description Shell command to execute inside the container
@@ -725,11 +775,133 @@ interface components {
              */
             command: string;
         };
+        ExecMount: {
+            /**
+             * @description Disk ID to mount at this relative path
+             * @example dsk-abc123
+             */
+            disk: string;
+            /**
+             * @description Subdirectory of the disk to expose at the mountpoint. Must be a
+             *     relative path with no `.` or `..` segments. When omitted, the
+             *     disk's root is exposed.
+             * @example app/logs
+             */
+            subdirectory?: string;
+            /**
+             * @description When true, the disk is mounted read-only inside the container.
+             *     Writes against the mount fail with EROFS.
+             * @default false
+             */
+            readOnly: boolean;
+        };
         ApiResponse_Exec: {
             /** @example true */
             success: boolean;
             data: components["schemas"]["ExecDiskResult"];
         };
+        GrepDiskRequest: {
+            /**
+             * @description Directory on the disk to search, relative to the disk root.
+             *     An empty string or "/" means the disk root.
+             * @example data/logs
+             */
+            directory: string;
+            /**
+             * @description Extended regular expression (passed to `grep -E`)
+             * @example ERROR|FATAL
+             */
+            pattern: string;
+            /**
+             * @description When true, walks subdirectories breadth-first.
+             * @default false
+             */
+            recursive: boolean;
+            /**
+             * @description Wall-clock deadline for the entire request. Capped at 30
+             *     seconds because the runtime exec container itself is bounded
+             *     at ~30s; longer requests would have their workers killed
+             *     mid-scan.
+             * @default 30
+             */
+            maxDurationSeconds: number;
+            /**
+             * @description Maximum number of parallel grep workers. Higher values finish
+             *     larger datasets within the deadline but consume more runtime
+             *     capacity. The controlplane clamps this to the fleet's
+             *     currently-available capacity.
+             * @default 50
+             */
+            concurrency: number;
+            /**
+             * @description Stop scanning once the aggregator has this many matches.
+             *     Returned matches are a sample of whichever workers reported
+             *     first, not the lexicographically first N.
+             * @default 1000
+             */
+            maxResults: number;
+        };
+        GrepMatch: {
+            /**
+             * @description Path to the file (relative to the disk root).
+             * @example data/logs/2026-05-03.log
+             */
+            file: string;
+            /**
+             * @description 1-based line number where the match occurred.
+             * @example 142
+             */
+            line: number;
+            /** @description The matching line. */
+            text: string;
+        };
+        /**
+         * @description Why the search stopped.
+         *     - `completed`: every file under the directory was scanned successfully.
+         *     - `incomplete`: pipeline ran to its natural end but one or more
+         *       batches errored (invalid regex, unreadable file, runtime issue).
+         *       Results may be partial or wrong; do not rely on completeness.
+         *     - `max_results`: hit `maxResults` before scanning everything.
+         *     - `deadline`: hit `maxDurationSeconds`.
+         *     - `list_failed`: directory listing failed; partial results
+         *       may be present.
+         * @enum {string}
+         */
+        GrepStoppedReason: "completed" | "incomplete" | "max_results" | "deadline" | "list_failed";
+        GrepDiskResult: {
+            matches: components["schemas"]["GrepMatch"][];
+            stoppedReason: components["schemas"]["GrepStoppedReason"];
+            /** @description Files actually fed to a grep container. */
+            filesScanned: number;
+            /** @description Number of grep containers started for this request. */
+            containersDispatched: number;
+            /**
+             * Format: double
+             * @description Sum of per-container execution time in seconds, measured by the
+             *     runtime. Approximates billable container-seconds.
+             */
+            computeSecondsUsed: number;
+            /** @description End-to-end wall clock measured by the server. */
+            durationMs: number;
+            /**
+             * @description Wall-clock time spent enumerating files via listObjects, from
+             *     the request's start to the moment listing fully drained (or
+             *     was canceled). Listing and matching overlap, so listingMs +
+             *     grepMs typically exceeds durationMs.
+             */
+            listingMs: number;
+            /**
+             * @description Wall-clock time spent matching, from the first grep container
+             *     being dispatched to the last container reporting results. 0 if
+             *     no batches ran.
+             */
+            grepMs: number;
+        };
+        ApiResponse_GrepDisk: {
+            /** @example true */
+            success: boolean;
+            data: components["schemas"]["GrepDiskResult"];
+        };
     };
     responses: {
         /** @description Invalid or missing authentication credentials */
@@ -1091,6 +1263,37 @@ interface operations {
             };
         };
     };
+    grepDisk: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Disk ID (format `dsk-{16 hex chars}`) */
+                id: components["parameters"]["DiskId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["GrepDiskRequest"];
+            };
+        };
+        responses: {
+            /** @description Grep completed (possibly stopped early) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_GrepDisk"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            500: components["responses"]["InternalError"];
+        };
+    };
     exec: {
         parameters: {
             query?: never;
@@ -1232,6 +1435,9 @@ type CreateApiTokenRequest = components["schemas"]["CreateApiTokenRequest"];
 type ApiTokenResponse = components["schemas"]["ApiTokenResponse"];
 type ExecDiskResult = components["schemas"]["ExecDiskResult"];
 type ExecRequest = components["schemas"]["ExecRequest"];
+type GrepDiskResult = components["schemas"]["GrepDiskResult"];
+type GrepMatch = components["schemas"]["GrepMatch"];
+type GrepStoppedReason = components["schemas"]["GrepStoppedReason"];
 type DiskStatus = DiskResponse["status"];
 
 interface MountOptions {
@@ -1241,6 +1447,34 @@ interface MountOptions {
     insecure?: boolean;
 }
 type ExecResult = ExecDiskResult;
+type GrepResult = GrepDiskResult;
+
+interface GrepOptions {
+    /**
+     * Directory on the disk to search, relative to the disk root. An empty
+     * string or "/" means the disk root.
+     */
+    directory: string;
+    /** Extended regular expression (passed to `grep -E`). */
+    pattern: string;
+    /** Walk subdirectories breadth-first. Defaults to false. */
+    recursive?: boolean;
+    /** Wall-clock deadline for the entire request. Defaults to 30s. */
+    maxDurationSeconds?: number;
+    /**
+     * Maximum number of parallel grep workers. Higher values finish larger
+     * datasets within the deadline but consume more runtime capacity. The
+     * controlplane clamps this to the fleet's currently-available capacity.
+     * Defaults to 50.
+     */
+    concurrency?: number;
+    /**
+     * Stop scanning once the aggregator has this many matches. Returned
+     * matches are a sample of whichever workers reported first, not the
+     * lexicographically first N. Defaults to 1000.
+     */
+    maxResults?: number;
+}
 declare class Disk {
     readonly id: string;
     readonly name: string;
@@ -1282,6 +1516,17 @@ declare class Disk {
      * Blocks until the command completes and returns stdout, stderr, and exit code.
      */
     exec(command: string): Promise<ExecResult>;
+    /**
+     * Constant-time parallel grep across files on this disk. Listing and
+     * matching are fanned out across ephemeral exec containers; the request
+     * finishes within the supplied time budget regardless of dataset size.
+     *
+     * The returned `stoppedReason` says whether the search ran to completion
+     * or short-circuited on `maxResults` / `maxDurationSeconds`. When
+     * stopping early, the matches returned are a sample (whichever workers
+     * reported first), not the lexicographically first N.
+     */
+    grep(opts: GrepOptions): Promise<GrepResult>;
     /**
      * Connect to this disk's data plane via the native ArchilClient.
      *
@@ -1344,11 +1589,34 @@ interface ArchilOptions {
     baseUrl?: string;
 }
 /**
- * One disk to mount, identified by a Disk instance or a raw disk id string.
- * Used by Archil#exec — the map key is the relative path under /mnt/archil
- * at which to mount the disk.
+ * Options that apply to a single mounted disk in an exec request.
+ * Use this object form when you need to pin the mount to a subdirectoryectory
+ * of the disk and/or mount it read-only; for the default case (mount
+ * the disk's root, read-write), pass a `Disk` or disk-id string instead.
+ */
+interface ExecMountSpec {
+    /** Disk to mount, by `Disk` instance or raw disk id string. */
+    disk: Disk | string;
+    /**
+     * Subdirectory of the disk to expose at the mountpoint. Must be a
+     * relative path with no `.` or `..` segments. When omitted, the disk's
+     * root is exposed.
+     */
+    subdirectory?: string;
+    /**
+     * When true, mount the disk read-only inside the container. Writes
+     * against the mount fail with EROFS. Defaults to false.
+     */
+    readOnly?: boolean;
+}
+/**
+ * One disk to mount in an exec request. Either a `Disk`/disk-id string
+ * (mounts the disk's root, read-write) or an `ExecMountSpec` object that
+ * additionally selects a subdirectoryectory of the disk and/or marks the mount
+ * as read-only. Used by Archil#exec — the map key is the relative path
+ * under /mnt/archil at which to mount the disk.
  */
-type ExecMount = Disk | string;
+type ExecMount = Disk | string | ExecMountSpec;
 interface ExecOptions {
     /**
      * Disks to mount, keyed by the relative path under `/mnt/archil` at which
@@ -1395,4 +1663,4 @@ declare function deleteApiKey(id: string): Promise<void>;
  */
 declare function exec(opts: ExecOptions): Promise<ExecDiskResult>;
 
-export { type ApiTokenResponse, Archil, ArchilApiError, type ArchilOptions, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };
+export { type ApiTokenResponse, Archil, ArchilApiError, type ArchilOptions, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type GrepMatch, type GrepOptions, type GrepResult, type GrepStoppedReason, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };

package/dist/index.d.ts

@@ -148,6 +148,48 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/disks/{id}/grep": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Constant-time parallel grep over a directory on a disk
+         * @description Searches files under a directory on the disk for lines matching a
+         *     regular expression. Listing and matching are fanned out across
+         *     ephemeral exec containers, so the request finishes within the user's
+         *     time budget regardless of the size of the directory.
+         *
+         *     The user controls cost and latency with three knobs:
+         *
+         *     - `maxDurationSeconds` is the wall-clock deadline.
+         *     - `concurrency` is the maximum number of parallel grep workers.
+         *       Higher concurrency finishes larger datasets within the deadline;
+         *       the controlplane clamps to the runtime fleet's current capacity.
+         *     - `maxResults` causes the search to short-circuit after the
+         *       aggregator has collected this many matches.
+         *
+         *     With `recursive: false` only files directly under `directory` are
+         *     searched. With `recursive: true` subdirectories are walked
+         *     breadth-first and grep workers are dispatched as soon as each level
+         *     finishes listing — listing and matching overlap.
+         *
+         *     The matches returned when stopping early on `maxResults` are a sample
+         *     of whichever workers reported first, not the lexicographically first
+         *     N. The response surfaces `stoppedReason` so callers can distinguish
+         *     completion from early termination.
+         */
+        post: operations["grepDisk"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/exec": {
         parameters: {
             query?: never;
@@ -711,13 +753,21 @@ interface components {
              * @description Map of relative path under `/mnt/archil` to the disk to mount
              *     there. At least one entry is required. Relative paths must be
              *     non-empty, non-absolute, and contain no `.` or `..` segments.
+             *
+             *     Each value is either a plain disk ID string (mounts the disk's
+             *     root, read-write) or an object that additionally selects a
+             *     subdirectory of the disk and/or marks the mount as read-only.
              * @example {
              *       "data": "dsk-abc123",
-             *       "logs": "dsk-def456"
+             *       "logs": {
+             *         "disk": "dsk-def456",
+             *         "subdirectory": "app/logs",
+             *         "readOnly": true
+             *       }
              *     }
              */
             disks: {
-                [key: string]: string;
+                [key: string]: string | components["schemas"]["ExecMount"];
             };
             /**
              * @description Shell command to execute inside the container
@@ -725,11 +775,133 @@ interface components {
              */
             command: string;
         };
+        ExecMount: {
+            /**
+             * @description Disk ID to mount at this relative path
+             * @example dsk-abc123
+             */
+            disk: string;
+            /**
+             * @description Subdirectory of the disk to expose at the mountpoint. Must be a
+             *     relative path with no `.` or `..` segments. When omitted, the
+             *     disk's root is exposed.
+             * @example app/logs
+             */
+            subdirectory?: string;
+            /**
+             * @description When true, the disk is mounted read-only inside the container.
+             *     Writes against the mount fail with EROFS.
+             * @default false
+             */
+            readOnly: boolean;
+        };
         ApiResponse_Exec: {
             /** @example true */
             success: boolean;
             data: components["schemas"]["ExecDiskResult"];
         };
+        GrepDiskRequest: {
+            /**
+             * @description Directory on the disk to search, relative to the disk root.
+             *     An empty string or "/" means the disk root.
+             * @example data/logs
+             */
+            directory: string;
+            /**
+             * @description Extended regular expression (passed to `grep -E`)
+             * @example ERROR|FATAL
+             */
+            pattern: string;
+            /**
+             * @description When true, walks subdirectories breadth-first.
+             * @default false
+             */
+            recursive: boolean;
+            /**
+             * @description Wall-clock deadline for the entire request. Capped at 30
+             *     seconds because the runtime exec container itself is bounded
+             *     at ~30s; longer requests would have their workers killed
+             *     mid-scan.
+             * @default 30
+             */
+            maxDurationSeconds: number;
+            /**
+             * @description Maximum number of parallel grep workers. Higher values finish
+             *     larger datasets within the deadline but consume more runtime
+             *     capacity. The controlplane clamps this to the fleet's
+             *     currently-available capacity.
+             * @default 50
+             */
+            concurrency: number;
+            /**
+             * @description Stop scanning once the aggregator has this many matches.
+             *     Returned matches are a sample of whichever workers reported
+             *     first, not the lexicographically first N.
+             * @default 1000
+             */
+            maxResults: number;
+        };
+        GrepMatch: {
+            /**
+             * @description Path to the file (relative to the disk root).
+             * @example data/logs/2026-05-03.log
+             */
+            file: string;
+            /**
+             * @description 1-based line number where the match occurred.
+             * @example 142
+             */
+            line: number;
+            /** @description The matching line. */
+            text: string;
+        };
+        /**
+         * @description Why the search stopped.
+         *     - `completed`: every file under the directory was scanned successfully.
+         *     - `incomplete`: pipeline ran to its natural end but one or more
+         *       batches errored (invalid regex, unreadable file, runtime issue).
+         *       Results may be partial or wrong; do not rely on completeness.
+         *     - `max_results`: hit `maxResults` before scanning everything.
+         *     - `deadline`: hit `maxDurationSeconds`.
+         *     - `list_failed`: directory listing failed; partial results
+         *       may be present.
+         * @enum {string}
+         */
+        GrepStoppedReason: "completed" | "incomplete" | "max_results" | "deadline" | "list_failed";
+        GrepDiskResult: {
+            matches: components["schemas"]["GrepMatch"][];
+            stoppedReason: components["schemas"]["GrepStoppedReason"];
+            /** @description Files actually fed to a grep container. */
+            filesScanned: number;
+            /** @description Number of grep containers started for this request. */
+            containersDispatched: number;
+            /**
+             * Format: double
+             * @description Sum of per-container execution time in seconds, measured by the
+             *     runtime. Approximates billable container-seconds.
+             */
+            computeSecondsUsed: number;
+            /** @description End-to-end wall clock measured by the server. */
+            durationMs: number;
+            /**
+             * @description Wall-clock time spent enumerating files via listObjects, from
+             *     the request's start to the moment listing fully drained (or
+             *     was canceled). Listing and matching overlap, so listingMs +
+             *     grepMs typically exceeds durationMs.
+             */
+            listingMs: number;
+            /**
+             * @description Wall-clock time spent matching, from the first grep container
+             *     being dispatched to the last container reporting results. 0 if
+             *     no batches ran.
+             */
+            grepMs: number;
+        };
+        ApiResponse_GrepDisk: {
+            /** @example true */
+            success: boolean;
+            data: components["schemas"]["GrepDiskResult"];
+        };
     };
     responses: {
         /** @description Invalid or missing authentication credentials */
@@ -1091,6 +1263,37 @@ interface operations {
             };
         };
     };
+    grepDisk: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Disk ID (format `dsk-{16 hex chars}`) */
+                id: components["parameters"]["DiskId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["GrepDiskRequest"];
+            };
+        };
+        responses: {
+            /** @description Grep completed (possibly stopped early) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_GrepDisk"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            500: components["responses"]["InternalError"];
+        };
+    };
     exec: {
         parameters: {
             query?: never;
@@ -1232,6 +1435,9 @@ type CreateApiTokenRequest = components["schemas"]["CreateApiTokenRequest"];
 type ApiTokenResponse = components["schemas"]["ApiTokenResponse"];
 type ExecDiskResult = components["schemas"]["ExecDiskResult"];
 type ExecRequest = components["schemas"]["ExecRequest"];
+type GrepDiskResult = components["schemas"]["GrepDiskResult"];
+type GrepMatch = components["schemas"]["GrepMatch"];
+type GrepStoppedReason = components["schemas"]["GrepStoppedReason"];
 type DiskStatus = DiskResponse["status"];
 
 interface MountOptions {
@@ -1241,6 +1447,34 @@ interface MountOptions {
     insecure?: boolean;
 }
 type ExecResult = ExecDiskResult;
+type GrepResult = GrepDiskResult;
+
+interface GrepOptions {
+    /**
+     * Directory on the disk to search, relative to the disk root. An empty
+     * string or "/" means the disk root.
+     */
+    directory: string;
+    /** Extended regular expression (passed to `grep -E`). */
+    pattern: string;
+    /** Walk subdirectories breadth-first. Defaults to false. */
+    recursive?: boolean;
+    /** Wall-clock deadline for the entire request. Defaults to 30s. */
+    maxDurationSeconds?: number;
+    /**
+     * Maximum number of parallel grep workers. Higher values finish larger
+     * datasets within the deadline but consume more runtime capacity. The
+     * controlplane clamps this to the fleet's currently-available capacity.
+     * Defaults to 50.
+     */
+    concurrency?: number;
+    /**
+     * Stop scanning once the aggregator has this many matches. Returned
+     * matches are a sample of whichever workers reported first, not the
+     * lexicographically first N. Defaults to 1000.
+     */
+    maxResults?: number;
+}
 declare class Disk {
     readonly id: string;
     readonly name: string;
@@ -1282,6 +1516,17 @@ declare class Disk {
      * Blocks until the command completes and returns stdout, stderr, and exit code.
      */
     exec(command: string): Promise<ExecResult>;
+    /**
+     * Constant-time parallel grep across files on this disk. Listing and
+     * matching are fanned out across ephemeral exec containers; the request
+     * finishes within the supplied time budget regardless of dataset size.
+     *
+     * The returned `stoppedReason` says whether the search ran to completion
+     * or short-circuited on `maxResults` / `maxDurationSeconds`. When
+     * stopping early, the matches returned are a sample (whichever workers
+     * reported first), not the lexicographically first N.
+     */
+    grep(opts: GrepOptions): Promise<GrepResult>;
     /**
      * Connect to this disk's data plane via the native ArchilClient.
      *
@@ -1344,11 +1589,34 @@ interface ArchilOptions {
     baseUrl?: string;
 }
 /**
- * One disk to mount, identified by a Disk instance or a raw disk id string.
- * Used by Archil#exec — the map key is the relative path under /mnt/archil
- * at which to mount the disk.
+ * Options that apply to a single mounted disk in an exec request.
+ * Use this object form when you need to pin the mount to a subdirectoryectory
+ * of the disk and/or mount it read-only; for the default case (mount
+ * the disk's root, read-write), pass a `Disk` or disk-id string instead.
+ */
+interface ExecMountSpec {
+    /** Disk to mount, by `Disk` instance or raw disk id string. */
+    disk: Disk | string;
+    /**
+     * Subdirectory of the disk to expose at the mountpoint. Must be a
+     * relative path with no `.` or `..` segments. When omitted, the disk's
+     * root is exposed.
+     */
+    subdirectory?: string;
+    /**
+     * When true, mount the disk read-only inside the container. Writes
+     * against the mount fail with EROFS. Defaults to false.
+     */
+    readOnly?: boolean;
+}
+/**
+ * One disk to mount in an exec request. Either a `Disk`/disk-id string
+ * (mounts the disk's root, read-write) or an `ExecMountSpec` object that
+ * additionally selects a subdirectoryectory of the disk and/or marks the mount
+ * as read-only. Used by Archil#exec — the map key is the relative path
+ * under /mnt/archil at which to mount the disk.
  */
-type ExecMount = Disk | string;
+type ExecMount = Disk | string | ExecMountSpec;
 interface ExecOptions {
     /**
      * Disks to mount, keyed by the relative path under `/mnt/archil` at which
@@ -1395,4 +1663,4 @@ declare function deleteApiKey(id: string): Promise<void>;
  */
 declare function exec(opts: ExecOptions): Promise<ExecDiskResult>;
 
-export { type ApiTokenResponse, Archil, ArchilApiError, type ArchilOptions, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };
+export { type ApiTokenResponse, Archil, ArchilApiError, type ArchilOptions, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type GrepMatch, type GrepOptions, type GrepResult, type GrepStoppedReason, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };

package/dist/index.js

@@ -217,6 +217,31 @@ var Disk = class {
       })
     );
   }
+  /**
+   * Constant-time parallel grep across files on this disk. Listing and
+   * matching are fanned out across ephemeral exec containers; the request
+   * finishes within the supplied time budget regardless of dataset size.
+   *
+   * The returned `stoppedReason` says whether the search ran to completion
+   * or short-circuited on `maxResults` / `maxDurationSeconds`. When
+   * stopping early, the matches returned are a sample (whichever workers
+   * reported first), not the lexicographically first N.
+   */
+  async grep(opts) {
+    return unwrap(
+      this._client.POST("/api/disks/{id}/grep", {
+        params: { path: { id: this.id } },
+        body: {
+          directory: opts.directory,
+          pattern: opts.pattern,
+          recursive: opts.recursive ?? false,
+          maxDurationSeconds: opts.maxDurationSeconds ?? 30,
+          concurrency: opts.concurrency ?? 50,
+          maxResults: opts.maxResults ?? 1e3
+        }
+      })
+    );
+  }
   /**
    * Connect to this disk's data plane via the native ArchilClient.
    *
@@ -332,6 +357,12 @@ var Tokens = class {
 };
 
 // src/archil.ts
+function isExecMountSpec(m) {
+  return typeof m === "object" && m !== null && "disk" in m;
+}
+function diskIdFromMount(m) {
+  return typeof m === "string" ? m : m.id;
+}
 var Archil = class {
   disks;
   tokens;
@@ -363,7 +394,16 @@ var Archil = class {
   async exec(opts) {
     const disks = {};
     for (const [relPath, mount] of Object.entries(opts.disks)) {
-      disks[relPath] = typeof mount === "string" ? mount : mount.id;
+      if (isExecMountSpec(mount)) {
+        const entry = {
+          disk: diskIdFromMount(mount.disk),
+          readOnly: mount.readOnly ?? false
+        };
+        if (mount.subdirectory !== void 0) entry.subdirectory = mount.subdirectory;
+        disks[relPath] = entry;
+      } else {
+        disks[relPath] = diskIdFromMount(mount);
+      }
     }
     return unwrap(
       this._client.POST("/api/exec", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "disk",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "description": "Pure-JS client and CLI for Archil disks",
   "type": "module",
   "main": "dist/index.cjs",