disk 0.8.18 → 0.8.20

package/dist/index.d.mts

@@ -0,0 +1,287 @@
+import { A as AwsStsUser, B as ExecRequest, C as S3Object, D as effectiveUploadPartSize, E as UploadPart, F as DiskMetrics, G as MountConfigResponse, H as GrepMatch, I as DiskResponse, J as S3CompatibleMount, K as MountResponse, L as DiskStatus, M as ConnectedClient, N as CreateApiTokenRequest, O as ApiTokenResponse, P as CreateDiskRequest, Q as ApiClient, R as DiskUser, S as PutObjectResult, T as ShareUrlResult, U as GrepStoppedReason, V as GCSMount, W as MountConfig, X as TokenUser, Y as S3Mount, Z as FileSystem, _ as MultipartUploadSummary, a as Disk, b as PartListing, c as GrepOptions, d as ListObjectsOptions, f as ListObjectsResult, g as MultipartUploadListing, h as MultipartUpload, i as DeleteObjectsResult, j as AzureBlobMount, k as AuthorizedUser, l as GrepResult, m as MountOptions, n as DeleteObjectsError, o as DiskMultipart, p as ListPartsOptions, q as R2Mount, r as DeleteObjectsOptions, s as ExecResult, t as CompletedMultipartUpload, u as ListMultipartUploadsOptions, v as ObjectMetadata, w as ShareUrlOptions, x as PutObjectOptions, y as PartInfo, z as ExecDiskResult } from "./disk-BLF7FFqG.mjs";
+
+//#region src/disks.d.ts
+interface ListDisksOptions {
+  /** Cap on the total number of disks returned. */
+  limit?: number;
+  /** Resume listing from a previous page's `nextCursor`. */
+  cursor?: string;
+  name?: string;
+}
+interface DiskListPage {
+  disks: Disk[];
+  /**
+   * Set when more disks remain beyond this page; pass it back as `cursor` to
+   * fetch the next one. Undefined on the last page.
+   */
+  nextCursor?: string;
+}
+interface CreateDiskResult {
+  disk: Disk;
+  token: string | null;
+  tokenIdentifier: string | null;
+  authorizedUsers: AuthorizedUser[];
+}
+declare class Disks {
+  /** @internal */
+  private readonly _client;
+  /** @internal */
+  private readonly _region;
+  /** @internal */
+  private readonly _s3BaseUrl?;
+  /** @internal */
+  constructor(client: ApiClient, region: string, s3BaseUrl?: string);
+  /**
+   * List the account's disks. Fetches in cursor-driven pages (bounded server
+   * work per request) and follows `nextCursor` until exhausted, so the result
+   * is complete even for very large accounts. Use `limit` to cap the total, or
+   * {@link listPage} to walk pages yourself.
+   */
+  list(opts?: ListDisksOptions): Promise<Disk[]>;
+  /**
+   * Fetch a single page of disks. `nextCursor` on the result resumes the
+   * listing (it can also be persisted, e.g. across requests of a paginated UI).
+   */
+  listPage(opts?: ListDisksOptions): Promise<DiskListPage>;
+  get(id: string): Promise<Disk>;
+  /**
+   * Create a new disk with an auto-generated mount token.
+   *
+   * Returns the Disk, the one-time token (save it — it cannot be retrieved
+   * again), and the token identifier for later management.
+   */
+  create(req: CreateDiskRequest): Promise<CreateDiskResult>;
+}
+//#endregion
+//#region src/tokens.d.ts
+interface ListTokensOptions {
+  limit?: number;
+  cursor?: string;
+}
+declare class Tokens {
+  /** @internal */
+  private readonly _client;
+  /** @internal */
+  constructor(client: ApiClient);
+  list(opts?: ListTokensOptions): Promise<ApiTokenResponse[]>;
+  create(req: CreateApiTokenRequest): Promise<ApiTokenResponse & {
+    token?: string;
+  }>;
+  delete(id: string): Promise<void>;
+}
+//#endregion
+//#region src/workspace.d.ts
+/** Anything that can run a multi-disk exec — i.e. an `Archil` client. A narrow
+ * structural type so this module doesn't import the Archil class (avoiding a
+ * value-import cycle with archil.ts). */
+interface WorkspaceExecCapable {
+  exec(opts: ExecOptions): Promise<ExecResult>;
+}
+/**
+ * A key-routed filesystem spanning several Archil disks. Each disk is mounted
+ * under a name and addressed as the first segment of a key (`<name>/...`);
+ * `getObject`, `putObject`, `deleteObject`, `listObjects`, and `grep` route to
+ * the right disk by that segment (and `listObjects` / `grep` fan out across all
+ * of them when the key/prefix doesn't name one). Implements the same
+ * {@link FileSystem} surface as a single {@link Disk}, so it works anywhere a
+ * disk does. Mounts can be changed at runtime with {@link addDisk} /
+ * {@link removeDisk}.
+ */
+declare class Workspace implements FileSystem {
+  private readonly client;
+  private readonly mounts;
+  /** @internal Use `archil.workspace({ ... })`. */
+  constructor(client: WorkspaceExecCapable, mounts: Record<string, ExecMount>);
+  /** Mount (or replace) a disk at `name`; its objects are addressed as
+   * `<name>/...`. Accepts a `Disk` or a mount spec (read-only / subdirectory /
+   * conditional / delegation checkouts); a bare disk-id string is rejected —
+   * fetch the disk first. */
+  addDisk(name: string, disk: ExecMount): this;
+  /** Unmount the disk at `name`. Returns whether a disk was removed. Refuses to
+   * remove the last disk — a workspace must always have at least one (the same
+   * invariant the constructor enforces), else fan-out/exec would have nothing to
+   * route to. */
+  removeDisk(name: string): boolean;
+  /** The names of the currently-mounted disks. */
+  diskNames(): string[];
+  private unknownDisk;
+  /** Resolve a workspace key (`<name>/...`) to the disk and the disk-relative key. */
+  private route;
+  /** Mounts touched by a key prefix; an empty prefix fans out to all of them. */
+  private covered;
+  /** Map a workspace-relative key to the disk's key, applying the mount's subdirectory. */
+  private diskKey;
+  /** Map a disk key back to its workspace key (`<name>/...`), stripping the mount subdirectory. */
+  private abs;
+  getObject(key: string): Promise<Uint8Array>;
+  putObject(key: string, body: string | Uint8Array | ArrayBuffer, contentType?: string): Promise<PutObjectResult>;
+  deleteObject(key: string): Promise<void>;
+  listObjects(prefix?: string, opts?: ListObjectsOptions): Promise<ListObjectsResult>;
+  grep(opts: GrepOptions): Promise<GrepResult>;
+  exec(command: string): Promise<ExecResult>;
+}
+//#endregion
+//#region src/archil.d.ts
+interface ArchilOptions {
+  /** API key. Falls back to ARCHIL_API_KEY env var if not provided. */
+  apiKey?: string;
+  /** Region. Falls back to ARCHIL_REGION env var if not provided. */
+  region?: string;
+  /** Override the control plane base URL (useful for testing). */
+  baseUrl?: string;
+  /**
+   * Override the S3-compatible API base URL used by Disk#getObject /
+   * putObject / deleteObject. Falls back to ARCHIL_S3_BASE_URL, then to the
+   * control plane URL with its `control.` hostname prefix swapped for `s3.`.
+   */
+  s3BaseUrl?: string;
+}
+/**
+ * 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 subdirectory
+ * of the disk, mount it read-only, mount it in conditional mode, or request
+ * delegation checkouts; for the default case (mount the disk's root,
+ * read-write with no checkout), 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;
+  /**
+   * When true, mount the disk in conditional mode, where mutating operations
+   * are sent directly to the server without a delegation checkout. This
+   * enables concurrent writes from multiple clients to the same disk.
+   * Defaults to false.
+   */
+  conditional?: boolean;
+  /**
+   * Milliseconds to wait in the delegation queue for each requested checkout.
+   * If set without `checkoutPaths`, the exposed mount root is acquired during
+   * mount setup. Cannot be combined with `readOnly: true`.
+   */
+  queueMs?: number;
+  /**
+   * Paths relative to this disk's exposed mount root to check out before the
+   * command starts. May be set without `queueMs`; those checkouts try
+   * immediately without waiting in the delegation queue. Cannot be combined
+   * with `readOnly: true`.
+   */
+  checkoutPaths?: string[];
+}
+/**
+ * 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 subdirectory of the disk and/or marks the mount as
+ * read-only, conditional, or requests delegation checkouts. Used
+ * by Archil#exec, where the map key is the relative path under /mnt/archil at
+ * which to mount the disk.
+ */
+type ExecMount = Disk | string | ExecMountSpec;
+interface ExecOptions {
+  /**
+   * Disks to mount, keyed by the relative path under `/mnt/archil` at which
+   * to mount each one. At least one entry is required. Paths must be
+   * non-empty, non-absolute, and contain no `.` or `..` segments.
+   */
+  disks: Record<string, ExecMount>;
+  /** Shell command to run inside the container. */
+  command: string;
+}
+declare class Archil {
+  readonly disks: Disks;
+  readonly tokens: Tokens;
+  /** @internal */
+  private readonly _client;
+  constructor(opts?: ArchilOptions);
+  /**
+   * Run a command in a container with multiple disks mounted simultaneously,
+   * each at its own relative path under `/mnt/archil`. Blocks until the
+   * command completes and returns its stdout, stderr, exit code, and timing.
+   */
+  exec(opts: ExecOptions): Promise<ExecDiskResult>;
+  /**
+   * Build an agent filesystem toolset spanning several disks at once. `mounts`
+   * maps a relative path to a disk (or `ExecMountSpec`), exactly like
+   * {@link exec}; each disk appears under `/mnt/archil/<path>`. Hand the result
+   * to a framework adapter (`createDiskTools(workspace)`) to get tools that route
+   * file operations by path and fan `grep`/`list_files` out across the disks.
+   */
+  workspace(mounts: Record<string, ExecMount>): Workspace;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Base class for every error the SDK throws. Catch with `instanceof ArchilError`
+ * to handle control-plane and S3 failures uniformly; `status` is the HTTP status
+ * code and `code` a machine-readable error code when the server provided one.
+ */
+declare class ArchilError extends Error {
+  /** HTTP status code associated with the failure. */
+  readonly status: number;
+  /** Machine-readable error code (e.g. an S3 code like "NoSuchKey"), if known. */
+  readonly code?: string;
+  constructor(message: string, status: number, code?: string);
+}
+/** Error from the control-plane REST API. */
+declare class ArchilApiError extends ArchilError {
+  constructor(message: string, status: number, code?: string);
+}
+/**
+ * Error from the S3-compatible object API (getObject/putObject/deleteObject/
+ * headObject/listObjects). The gateway returns an S3-style XML `<Error>` body;
+ * this surfaces its parts as structured fields (`status`, `code`, `requestId`)
+ * rather than a raw blob, while keeping the full body on `raw` for debugging.
+ */
+declare class ArchilS3Error extends ArchilError {
+  /** S3 request id, if the gateway returned one. */
+  readonly requestId?: string;
+  /** Raw response body (the XML document), for debugging. */
+  readonly raw: string;
+  constructor(opts: {
+    operation: string;
+    statusCode: number;
+    statusText?: string;
+    code?: string;
+    message?: string;
+    requestId?: string;
+    raw: string;
+  });
+}
+//#endregion
+//#region src/version.d.ts
+declare const VERSION: string;
+declare const USER_AGENT: string;
+//#endregion
+//#region src/index.d.ts
+declare function configure(options: ArchilOptions): void;
+declare function createDisk(req: CreateDiskRequest): Promise<CreateDiskResult>;
+declare function listDisks(opts?: ListDisksOptions): Promise<Disk[]>;
+declare function getDisk(id: string): Promise<Disk>;
+declare function listApiKeys(opts?: ListTokensOptions): Promise<ApiTokenResponse[]>;
+declare function createApiKey(req: CreateApiTokenRequest): Promise<ApiTokenResponse & {
+  token?: string;
+}>;
+declare function deleteApiKey(id: string): Promise<void>;
+/**
+ * Run a command in a container with multiple disks mounted simultaneously,
+ * each at its own relative path under `/mnt/archil`. Blocks until the
+ * command completes and returns its stdout, stderr, exit code, and timing.
+ */
+declare function exec(opts: ExecOptions): Promise<ExecDiskResult>;
+/**
+ * Build an agent filesystem toolset spanning several disks, using the
+ * module-level client. See {@link Archil.workspace}.
+ */
+declare function workspace(mounts: Record<string, ExecMount>): Workspace;
+//#endregion
+export { type ApiTokenResponse, Archil, ArchilApiError, ArchilError, type ArchilOptions, ArchilS3Error, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type CompletedMultipartUpload, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, type DeleteObjectsError, type DeleteObjectsOptions, type DeleteObjectsResult, Disk, type DiskListPage, type DiskMetrics, DiskMultipart, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type FileSystem, type GCSMount, type GrepMatch, type GrepOptions, type GrepResult, type GrepStoppedReason, type ListDisksOptions, type ListMultipartUploadsOptions, type ListObjectsOptions, type ListObjectsResult, type ListPartsOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type MultipartUpload, type MultipartUploadListing, type MultipartUploadSummary, type ObjectMetadata, type PartInfo, type PartListing, type PutObjectOptions, type PutObjectResult, type R2Mount, type S3CompatibleMount, type S3Mount, type S3Object, type ShareUrlOptions, type ShareUrlResult, type TokenUser, Tokens, USER_AGENT, type UploadPart, VERSION, Workspace, configure, createApiKey, createDisk, deleteApiKey, effectiveUploadPartSize, exec, getDisk, listApiKeys, listDisks, workspace };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { _ as USER_AGENT, a as exec, b as ArchilError, c as listDisks, d as Workspace, f as Tokens, g as effectiveUploadPartSize, h as DiskMultipart, i as deleteApiKey, l as workspace, m as Disk, n as createApiKey, o as getDisk, p as Disks, r as createDisk, s as listApiKeys, t as configure, u as Archil, v as VERSION, x as ArchilS3Error, y as ArchilApiError } from "./src-BuqSzAcO.mjs";
+export { Archil, ArchilApiError, ArchilError, ArchilS3Error, Disk, DiskMultipart, Disks, Tokens, USER_AGENT, VERSION, Workspace, configure, createApiKey, createDisk, deleteApiKey, effectiveUploadPartSize, exec, getDisk, listApiKeys, listDisks, workspace };

package/dist/internal/tools.cjs

@@ -0,0 +1,328 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_paths = require("../paths-1c4QqbOB.cjs");
+let zod = require("zod");
+//#region src/internal/tools.ts
+/** Translate an agent-facing path to the filesystem key the {@link FileSystem}
+* methods take. Strips the container mount root (`/mnt` for a single disk,
+* `/mnt/archil` for a workspace) so a path copied from a `run_bash` command
+* resolves the same, drops the leading slash, and resolves `.`/`..`. For a
+* workspace the result's first segment is the disk name (which the workspace
+* routes on); for a single disk it is a plain disk key. */
+function toKey(ctx, path) {
+	return require_paths.toSegments(path, ctx.execRoot).join("/");
+}
+/** Build a {@link ToolContext} from any filesystem. A workspace is detected by
+* its `diskNames()` method (duck-typed so this layer needn't import the class);
+* its disks are top-level directories, whereas a single disk is rooted at `/`. */
+function buildContext(fs) {
+	const withNames = fs;
+	if (typeof withNames.diskNames === "function") {
+		const names = withNames.diskNames();
+		return {
+			fs,
+			execRoot: "/mnt/archil",
+			layoutHint: `Files live on these disks, each a top-level directory: ${names.map((n) => `/${n}/…`).join(", ")}. Use absolute paths like /${names[0] ?? "data"}/reports/q1.csv.`
+		};
+	}
+	return {
+		fs,
+		execRoot: "/mnt",
+		layoutHint: "Files live under / (the disk root). Use absolute paths like /reports/q1.csv."
+	};
+}
+/** Root a grep match path with a leading slash. A workspace already roots paths
+* by disk (`/data/...`); a single disk reports disk-relative keys (`reports/...`),
+* so prefix `/` to present both consistently. */
+function rootMatchPath(file) {
+	return file.startsWith("/") ? file : `/${file}`;
+}
+const DEFAULT_GLOB_LIMIT = 100;
+const MAX_GLOB_LIMIT = 1e3;
+const MAX_GLOB_OUTPUT_BYTES = 50 * 1024;
+function normalizeSearchPath(ctx, path) {
+	const key = toKey(ctx, path);
+	return {
+		key,
+		path: rootMatchPath(key)
+	};
+}
+function globLimit(limit) {
+	return Math.min(Math.max(1, limit ?? DEFAULT_GLOB_LIMIT), MAX_GLOB_LIMIT);
+}
+function isGitPath(path) {
+	return path.split("/").includes(".git");
+}
+function basename(path) {
+	return path.split("/").pop() ?? path;
+}
+function relativeToSearchPath(key, searchKey) {
+	if (!searchKey) return key;
+	return key.slice(searchKey.length).replace(/^\/+/, "");
+}
+function globMatcher(pattern) {
+	const regexes = expandBraces(pattern).map((p) => globToRegExp(p));
+	return (path) => regexes.some((regex) => regex.test(path));
+}
+function expandBraces(pattern) {
+	const start = pattern.indexOf("{");
+	if (start < 0) return [pattern];
+	const end = pattern.indexOf("}", start + 1);
+	if (end < 0) return [pattern];
+	const before = pattern.slice(0, start);
+	const after = pattern.slice(end + 1);
+	return pattern.slice(start + 1, end).split(",").flatMap((part) => expandBraces(`${before}${part}${after}`));
+}
+function globToRegExp(pattern) {
+	let source = "^";
+	for (let i = 0; i < pattern.length; i += 1) {
+		const char = pattern[i];
+		if (char === "*") {
+			if (pattern[i + 1] === "*") {
+				i += 1;
+				if (pattern[i + 1] === "/") {
+					i += 1;
+					source += "(?:[^/]+/)*";
+				} else source += ".*";
+			} else source += "[^/]*";
+			continue;
+		}
+		if (char === "?") {
+			source += "[^/]";
+			continue;
+		}
+		if (char === "[") {
+			const end = pattern.indexOf("]", i + 1);
+			if (end > i + 1) {
+				const raw = pattern.slice(i + 1, end);
+				const negated = raw.startsWith("!");
+				source += `[${negated ? "^" : ""}${escapeCharacterClass(negated ? raw.slice(1) : raw)}]`;
+				i = end;
+				continue;
+			}
+		}
+		source += escapeRegExp(char);
+	}
+	return new RegExp(`${source}$`);
+}
+function escapeRegExp(value) {
+	return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+function escapeCharacterClass(value) {
+	return value.replace(/[\\\]]/g, "\\$&");
+}
+function matchesGlob(pattern, key, searchKey, absolute) {
+	const matcher = globMatcher(pattern);
+	if (absolute) return matcher(key);
+	const relative = relativeToSearchPath(key, searchKey);
+	if (pattern.includes("/")) return matcher(relative) || matcher(key);
+	return matcher(basename(relative));
+}
+function formatGlobResult(paths, limit, listingTruncated, path) {
+	const limited = paths.slice(0, limit);
+	const lines = [];
+	let bytes = 0;
+	let outputTruncated = false;
+	for (const line of limited) {
+		const lineBytes = new TextEncoder().encode(line).length + 1;
+		if (bytes + lineBytes > MAX_GLOB_OUTPUT_BYTES && lines.length > 0) {
+			outputTruncated = true;
+			break;
+		}
+		lines.push(line);
+		bytes += lineBytes;
+	}
+	if (lines.length === 0) return {
+		content: "No files found",
+		count: 0,
+		path,
+		truncated: listingTruncated
+	};
+	const truncated = listingTruncated || paths.length > limit || outputTruncated;
+	const count = lines.length;
+	if (truncated) {
+		lines.push("");
+		lines.push(`(Results truncated: showing first ${count} results out of more. Use a more specific path or pattern to narrow results.)`);
+	}
+	return {
+		content: lines.join("\n"),
+		count,
+		path,
+		truncated
+	};
+}
+function grepStatus(reason, matches) {
+	switch (reason) {
+		case "completed": return "Search completed.";
+		case "max_results": return `More matches exist; returned ${matches}.`;
+		case "deadline": return "Search hit the time limit; results may be incomplete.";
+		case "incomplete": return "Some files could not be searched; results may be incomplete.";
+		case "list_failed": return "Listing failed for part of the tree; results may be partial.";
+	}
+}
+function defineSpec(spec) {
+	return spec;
+}
+const SPECS = [
+	defineSpec({
+		name: "read_file",
+		description: "Read the contents of a text file and return them.",
+		schema: zod.z.object({ path: zod.z.string().describe("Path to the file from the filesystem root, e.g. /reports/q1.csv.") }),
+		async handler(ctx, args) {
+			const path = args.path;
+			const bytes = await ctx.fs.getObject(toKey(ctx, path));
+			try {
+				return {
+					content: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+					bytes: bytes.length
+				};
+			} catch {
+				return {
+					binary: true,
+					bytes: bytes.length
+				};
+			}
+		}
+	}),
+	defineSpec({
+		name: "write_file",
+		description: "Create or overwrite a file with the given text content.",
+		schema: zod.z.object({
+			path: zod.z.string().describe("Path to the file from the filesystem root, e.g. /reports/q1.csv."),
+			content: zod.z.string().describe("Full contents to write.")
+		}),
+		async handler(ctx, args) {
+			await ctx.fs.putObject(toKey(ctx, args.path), args.content);
+			return { bytes: new TextEncoder().encode(args.content).length };
+		}
+	}),
+	defineSpec({
+		name: "delete_file",
+		description: "Delete a file. Succeeds even if the file does not exist.",
+		schema: zod.z.object({ path: zod.z.string().describe("Path to the file from the filesystem root, e.g. /reports/q1.csv.") }),
+		async handler(ctx, args) {
+			await ctx.fs.deleteObject(toKey(ctx, args.path));
+			return {};
+		}
+	}),
+	defineSpec({
+		name: "list_files",
+		description: "List files and subdirectories. Omit 'path' to list from the root. Set 'recursive' to list the whole subtree.",
+		schema: zod.z.object({
+			path: zod.z.string().optional().describe("Directory to list (optional)."),
+			recursive: zod.z.boolean().optional().describe("List the full subtree.")
+		}),
+		async handler(ctx, args) {
+			const path = args.path || "/";
+			const recursive = args.recursive ?? false;
+			const dir = toKey(ctx, path);
+			const result = await ctx.fs.listObjects(dir ? `${dir}/` : void 0, { recursive });
+			const entries = [...result.commonPrefixes.map((cp) => ({
+				type: "dir",
+				path: `/${cp.replace(/\/+$/, "")}/`
+			})), ...result.objects.map((obj) => ({
+				type: "file",
+				path: `/${obj.key}`,
+				bytes: obj.size
+			}))];
+			entries.sort((a, b) => a.path.localeCompare(b.path) || a.type.localeCompare(b.type));
+			return result.isTruncated ? {
+				entries,
+				isTruncated: true
+			} : { entries };
+		}
+	}),
+	defineSpec({
+		name: "glob",
+		description: "Find files by glob pattern. Use this to look up filenames by pattern; use grep to search file contents.",
+		schema: zod.z.object({
+			pattern: zod.z.string().describe("Glob pattern to match, e.g. \"**/*.ts\" or \"src/**/*.js\"."),
+			path: zod.z.string().optional().describe("Directory to search from (optional)."),
+			limit: zod.z.number().int().optional().describe("Maximum number of results to return (default 100, max 1000).")
+		}),
+		async handler(ctx, args) {
+			const search = normalizeSearchPath(ctx, args.path || "/");
+			const absolutePattern = args.pattern.startsWith("/");
+			const pattern = absolutePattern ? toKey(ctx, args.pattern) : args.pattern;
+			const limit = globLimit(args.limit);
+			const result = await ctx.fs.listObjects(search.key ? `${search.key}/` : void 0, { recursive: true });
+			return formatGlobResult(result.objects.map((obj) => obj.key).filter((key) => !isGitPath(key) && matchesGlob(pattern, key, search.key, absolutePattern)).map(rootMatchPath).sort(), limit, result.isTruncated, search.path);
+		}
+	}),
+	defineSpec({
+		name: "grep",
+		description: "Search file contents for an extended regular expression and return matching lines as path:line: text. Searches recursively by default.",
+		schema: zod.z.object({
+			pattern: zod.z.string().describe("Extended regex (grep -E)."),
+			path: zod.z.string().optional().describe("Directory to search (optional)."),
+			recursive: zod.z.boolean().optional().describe("Search subdirectories (default true)."),
+			maxResults: zod.z.number().int().optional().describe("Cap on matches (default 200).")
+		}),
+		async handler(ctx, args) {
+			const path = args.path || "/";
+			const recursive = args.recursive ?? true;
+			const maxResults = args.maxResults ?? 200;
+			const result = await ctx.fs.grep({
+				pattern: args.pattern,
+				directory: toKey(ctx, path),
+				recursive,
+				maxResults
+			});
+			return {
+				matches: result.matches.map((m) => ({
+					path: rootMatchPath(m.file),
+					line: m.line,
+					text: m.text
+				})),
+				status: grepStatus(result.stoppedReason, result.matches.length),
+				filesScanned: result.filesScanned
+			};
+		}
+	}),
+	defineSpec({
+		name: "run_bash",
+		description: "Run a bash command in an ephemeral sandbox with the filesystem mounted. The working directory is the filesystem root, so paths match the other tools. Returns the exit code, stdout, and stderr.",
+		schema: zod.z.object({ command: zod.z.string().describe("The bash command to run.") }),
+		async handler(ctx, args) {
+			const result = await ctx.fs.exec(`cd ${ctx.execRoot} && ${args.command}`);
+			return {
+				exitCode: result.exitCode,
+				stdout: result.stdout,
+				stderr: result.stderr,
+				timing: result.timing
+			};
+		}
+	})
+];
+function formatError(error, args) {
+	const status = error?.status;
+	if (status === 404 && typeof args.path === "string") return { error: {
+		message: "file not found",
+		status,
+		path: args.path
+	} };
+	return { error: { message: error instanceof Error ? error.message : String(error) } };
+}
+/**
+* Bind the specs to a filesystem. The layout hint is appended to each
+* description so the model knows where files live, and `invoke` returns
+* expected failures as structured error objects rather than throwing.
+*/
+function bindSpecs(fs) {
+	const ctx = buildContext(fs);
+	return SPECS.map((spec) => ({
+		name: spec.name,
+		description: `${spec.description} ${ctx.layoutHint}`,
+		schema: spec.schema,
+		async invoke(args) {
+			const input = args ?? {};
+			try {
+				return await spec.handler(ctx, input);
+			} catch (error) {
+				return formatError(error, input);
+			}
+		}
+	}));
+}
+//#endregion
+exports.bindSpecs = bindSpecs;
+exports.buildContext = buildContext;