@xandreed/plugin-workspace 0.0.0-stage → 0.15.0

package/dist/local-system.entity.d.ts

@@ -0,0 +1,47 @@
+import { Schema } from "effect";
+/**
+ * How `BashLive` (and `localSystemPlugin`) runs commands. `shell` is the
+ * program commands run with (`<shell> -c <command>`): a name looked up once,
+ * when the layer is built, on the parent environment's `PATH` (its absolute
+ * entries), or an absolute path; there is no fallback, so a host without
+ * bash sets `shell: "sh"` (or another path) itself. With `killBackground`, a
+ * command's whole process group is killed when the command returns, so
+ * nothing it started in the background outlives it (a timeout or an
+ * interrupted caller always kills the group). `exitGraceMs` is how long,
+ * after the command exits, its output may take to close (a background
+ * process that kept it open) before the stream ends without the rest. The
+ * output pipes close then, so a background process kept with
+ * `killBackground: false` must have its own output (`cmd > log 2>&1 &`):
+ * one still writing to the command's dies of `SIGPIPE` or gets `EPIPE`.
+ *
+ * @public
+ */
+export declare const LocalSystemConfig: Schema.Struct<{
+    readonly shell: Schema.NonEmptyString;
+    readonly killBackground: Schema.Boolean;
+    readonly exitGraceMs: Schema.Int;
+    /** The host's base environment, or null to inherit from the agent process. Filtered per command by `resolveBashEnv`. */
+    readonly parentEnv: Schema.NullOr<Schema.$Record<Schema.String, Schema.String>>;
+}>;
+export type LocalSystemConfig = typeof LocalSystemConfig.Type;
+/** @public */
+export declare const localSystemDefaults: LocalSystemConfig;
+/**
+ * `BashLive`'s options: the plugin's configuration, each part optional, and
+ * `parentEnv`, the environment commands inherit from (filtered by
+ * `resolveBashEnv`) and the shell is looked up on; `process.env` when not
+ * given or null.
+ *
+ * @public
+ */
+export type BashLiveOptions = Partial<Omit<LocalSystemConfig, "parentEnv">> & {
+    readonly parentEnv?: Readonly<Record<string, string | undefined>> | null;
+};
+/** How a spawned process ended, as Node reports it, and whether the adapter killed it for running past its timeout. */
+export declare const ProcessEnd: Schema.Struct<{
+    readonly code: Schema.NullOr<Schema.Int>;
+    readonly signal: Schema.NullOr<Schema.String>;
+    readonly timedOut: Schema.Boolean;
+    readonly durationMs: Schema.Number;
+}>;
+export type ProcessEnd = typeof ProcessEnd.Type;

package/dist/local-system.entity.functions.d.ts

@@ -0,0 +1,53 @@
+import { Option, Result } from "effect";
+import type { BashExit, FsReason } from "@xandreed/core";
+import type { ProcessEnd } from "./local-system.entity.js";
+/** A thrown value's message, for the `message` of the error it becomes. */
+export declare const errorMessageOf: (error: unknown) => string;
+/**
+ * The `FsReason` of a failed node:fs call, from its error code: `ENOENT`
+ * is `NotFound`, `EEXIST` `Exists`, `EISDIR` (and Node's `ERR_FS_EISDIR`)
+ * `IsDirectory`, `ENOTDIR` `NotDirectory`, `ENOTEMPTY` `NotEmpty`, `EACCES`
+ * and `EPERM` `Permission`; `EINVAL`, a symbolic link loop (`ELOOP`), a
+ * name too long and an unusable argument (a path with a NUL byte) are
+ * `Invalid`; anything else, or no code at all, is `Io`.
+ *
+ * @public
+ */
+export declare const fsReasonOf: (error: unknown) => FsReason;
+export declare const rgReasonOf: (code: number) => FsReason;
+/**
+ * Whether a write to a command's standard input failed only because the
+ * command no longer reads it: it exited or closed its input first (`EPIPE`),
+ * or the stream was already torn down (`ERR_STREAM_DESTROYED`). The command
+ * is free to ignore its input, so these are not failures.
+ */
+export declare const isClosedInput: (error: unknown) => boolean;
+/**
+ * Where to look for an executable: an absolute path is itself; a bare name
+ * is tried in each absolute directory of `path` (a `PATH` value), in order;
+ * relative and empty entries, which would depend on the current directory,
+ * are skipped, as is a relative name with a slash.
+ */
+export declare const executableCandidates: (name: string, path: Option.Option<string>) => ReadonlyArray<string>;
+/**
+ * Where `remove(path)` acts, or why it never does. Trailing slashes are
+ * ignored, so a link named with one is still the link. The root (`/`, `//`)
+ * is refused, and so is a path whose last segment is `.` or `..`: such a
+ * path names a directory only by where it leads (`<link>/..` can be the
+ * root), so it is never removed. Otherwise the place is the parent as
+ * written (to be resolved, links and all) and the last name, never followed.
+ */
+export declare const removalPlace: (path: string) => Result.Result<{
+    readonly parent: string;
+    readonly name: string;
+}, string>;
+/** `name` in the directory `dir` (an absolute, resolved path). */
+export declare const pathIn: (dir: string, name: string) => string;
+/**
+ * A process's end as the `BashExit` the stream closes with. A process the
+ * adapter killed for its timeout ends `timeout` (it has no exit code, and its
+ * signal is the one that killed it); one a signal killed ends `signal`;
+ * otherwise it exited, with its code. A process that exited on its own just
+ * as its timeout came keeps its exit code and ends `exit`.
+ */
+export declare const bashExitOf: (end: ProcessEnd) => BashExit;

package/dist/local-system.entity.functions.js

@@ -0,0 +1,46 @@
+import { Option, Result } from "effect";
+import { errorCodeOf } from "@xandreed/core";
+export const errorMessageOf = (error) => error instanceof Error ? error.message : String(error);
+const reasons = new Map([
+  ["ENOENT", "NotFound"],
+  ["EEXIST", "Exists"],
+  ["EISDIR", "IsDirectory"],
+  ["ERR_FS_EISDIR", "IsDirectory"],
+  ["ENOTDIR", "NotDirectory"],
+  ["ENOTEMPTY", "NotEmpty"],
+  ["EACCES", "Permission"],
+  ["EPERM", "Permission"],
+  ["EINVAL", "Invalid"],
+  ["ELOOP", "Invalid"],
+  ["ENAMETOOLONG", "Invalid"],
+  ["ERR_INVALID_ARG_VALUE", "Invalid"]
+]);
+export const fsReasonOf = (error) => Option.match(errorCodeOf(error), {
+  onNone: () => "Io",
+  onSome: (code) => reasons.get(code) ?? "Io"
+});
+const rgReasons = new Map([
+  [1, "Permission"],
+  [13, "Permission"],
+  [2, "NotFound"],
+  [20, "NotDirectory"],
+  [21, "IsDirectory"],
+  [22, "Invalid"],
+  [36, "Invalid"],
+  [40, "Invalid"],
+  [62, "Invalid"],
+  [63, "Invalid"]
+]);
+export const rgReasonOf = (code) => rgReasons.get(code) ?? "Io", isClosedInput = (error) => Option.match(errorCodeOf(error), { onNone: () => !1, onSome: (code) => code === "EPIPE" || code === "ERR_STREAM_DESTROYED" }), executableCandidates = (name, path) => name.startsWith("/") ? [name] : name.includes("/") || name.length === 0 ? [] : Option.getOrElse(path, () => "").split(":").filter((dir) => dir.startsWith("/")).map((dir) => `${dir.endsWith("/") ? dir.slice(0, -1) : dir}/${name}`), removalPlace = (path) => {
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  return !path.startsWith("/") ? Result.fail(`paths must be absolute: ${path}`) : Option.match(Option.fromNullishOr(segments.at(-1)), {
+    onNone: () => Result.fail("the root directory is never removed"),
+    onSome: (name) => name === "." || name === ".." ? Result.fail(`a path whose last segment is ${name} is never removed: ${path}`) : Result.succeed({ parent: `/${segments.slice(0, -1).join("/")}`, name })
+  });
+}, pathIn = (dir, name) => dir.endsWith("/") ? `${dir}${name}` : `${dir}/${name}`, bashExitOf = (end) => ({
+  _tag: "BashExit",
+  termination: end.code !== null ? "exit" : end.timedOut ? "timeout" : end.signal !== null ? "signal" : "exit",
+  exitCode: Option.fromNullishOr(end.code),
+  signal: Option.fromNullishOr(end.signal),
+  durationMs: end.durationMs
+});

package/dist/local-system.entity.js

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+export const LocalSystemConfig = Schema.Struct({
+  shell: Schema.NonEmptyString,
+  killBackground: Schema.Boolean,
+  exitGraceMs: Schema.Int.pipe(Schema.check(Schema.isBetween({ minimum: 0, maximum: 60000 }))),
+  parentEnv: Schema.NullOr(Schema.Record(Schema.String, Schema.String))
+}), localSystemDefaults = { shell: "bash", killBackground: !0, exitGraceMs: 500, parentEnv: null }, ProcessEnd = Schema.Struct({
+  code: Schema.NullOr(Schema.Int),
+  signal: Schema.NullOr(Schema.String),
+  timedOut: Schema.Boolean,
+  durationMs: Schema.Number
+});

package/dist/plugin.adapter.d.ts

@@ -0,0 +1,183 @@
+import { Layer } from "effect";
+import { Bash, Capabilities, FileSystem, ImageResizer } from "@xandreed/core";
+/**
+ * The machine the agent runs on as its `FileSystem` and `Bash`: the local
+ * disk (`FileSystemLive`) and commands run with the configured shell
+ * (`BashLive`), built once per agent. Activation fails when the shell is not
+ * installed. Commands inherit `parentEnv` (the host process's environment
+ * when null) through `resolveBashEnv`'s allowlist.
+ */
+export declare const localSystemPlugin: import("@xandreed/core").TypedPlugin<{
+    readonly shell: string;
+    readonly killBackground: boolean;
+    readonly exitGraceMs: number;
+    readonly parentEnv: {
+        readonly [x: string]: string;
+    } | null;
+}, {
+    readonly shell: string;
+    readonly killBackground: boolean;
+    readonly exitGraceMs: number;
+    readonly parentEnv: {
+        readonly [x: string]: string;
+    } | null;
+}, FileSystem | Bash, import("@xandreed/core").BashError, never>;
+/**
+ * The local system as a typed layer: provides FileSystem and Bash; requires nothing.
+ *
+ * @public
+ */
+export declare const LocalSystemPluginLive: (options?: {
+    readonly shell?: string;
+    readonly killBackground?: boolean;
+    readonly exitGraceMs?: number;
+    readonly parentEnv?: {
+        readonly [x: string]: string | undefined;
+    } | null;
+} | undefined) => Layer.Layer<FileSystem | Bash, import("@xandreed/core").HarnessError | import("@xandreed/core").BashError, never>;
+/**
+ * The workspace tools (`workspaceTools`): read, ls, find and grep always on,
+ * write and edit behind `fs.write`, bash behind `shell.exec`, over the
+ * `FileSystem`, `Bash` and `SessionEnvironment` of each call. Built once
+ * per agent, so two sessions editing one file wait for each other. `Bash`
+ * is optional: without it there is no `bash` tool. Hosts grant the
+ * permissions through tool discovery's `grants` or a turn's
+ * `PermissionGrants`.
+ */
+export declare const workspaceToolsPlugin: import("@xandreed/core").TypedPlugin<{
+    readonly tools: readonly ("find" | "write" | "read" | "grep" | "bash" | "ls" | "edit")[];
+    readonly always: readonly ("read" | "edit" | "shell")[];
+    readonly confine: boolean;
+    readonly workspaceAccess: "write" | "read";
+    readonly roots: readonly {
+        readonly path: string;
+        readonly access: "write" | "read";
+    }[];
+    readonly protect: readonly string[];
+    readonly exclude: readonly string[];
+    readonly maxLines: number;
+    readonly maxBytes: number;
+    readonly lsEntries: number;
+    readonly findResults: number;
+    readonly grepMatches: number;
+    readonly grepLineChars: number;
+    readonly grepEngine: "auto" | "ripgrep" | "builtin";
+    readonly grepTimeoutMs: number;
+    readonly grepIgnoreFiles: boolean;
+    readonly maxFileBytes: number;
+    readonly readImages: boolean;
+    readonly imageMaxSide: number;
+    readonly fuzzyEdit: boolean;
+    readonly bashTimeoutMs: number;
+    readonly bashMaxTimeoutMs: number;
+    readonly bashEnv: {
+        readonly [x: string]: string;
+    };
+    readonly bashInheritEnv: boolean;
+    readonly bashEnvAllow: readonly string[];
+    readonly bashSessionEnv: boolean;
+    readonly spillDir: string | null;
+    readonly spillKeep: number;
+    readonly progressMs: number;
+    readonly environmentSection: boolean;
+    readonly sectionOrder: number;
+}, {
+    readonly tools: readonly ("find" | "write" | "read" | "grep" | "bash" | "ls" | "edit")[];
+    readonly always: readonly ("read" | "edit" | "shell")[];
+    readonly confine: boolean;
+    readonly workspaceAccess: "write" | "read";
+    readonly roots: readonly {
+        readonly path: string;
+        readonly access: "write" | "read";
+    }[];
+    readonly protect: readonly string[];
+    readonly exclude: readonly string[];
+    readonly maxLines: number;
+    readonly maxBytes: number;
+    readonly lsEntries: number;
+    readonly findResults: number;
+    readonly grepMatches: number;
+    readonly grepLineChars: number;
+    readonly grepEngine: "auto" | "ripgrep" | "builtin";
+    readonly grepTimeoutMs: number;
+    readonly grepIgnoreFiles: boolean;
+    readonly maxFileBytes: number;
+    readonly readImages: boolean;
+    readonly imageMaxSide: number;
+    readonly fuzzyEdit: boolean;
+    readonly bashTimeoutMs: number;
+    readonly bashMaxTimeoutMs: number;
+    readonly bashEnv: {
+        readonly [x: string]: string;
+    };
+    readonly bashInheritEnv: boolean;
+    readonly bashEnvAllow: readonly string[];
+    readonly bashSessionEnv: boolean;
+    readonly spillDir: string | null;
+    readonly spillKeep: number;
+    readonly progressMs: number;
+    readonly environmentSection: boolean;
+    readonly sectionOrder: number;
+}, Capabilities, import("@xandreed/core").HarnessError, never>;
+/**
+ * The workspace tools as a typed layer: contributes their capability; its handlers need FileSystem and SessionEnvironment (and Bash for bash) where the tools are opened.
+ *
+ * @public
+ */
+export declare const WorkspaceToolsPluginLive: (options?: {
+    readonly tools?: readonly ("find" | "write" | "read" | "grep" | "bash" | "ls" | "edit")[];
+    readonly always?: readonly ("read" | "edit" | "shell")[];
+    readonly confine?: boolean;
+    readonly workspaceAccess?: "write" | "read";
+    readonly roots?: readonly {
+        readonly path: string;
+        readonly access: "write" | "read";
+    }[];
+    readonly protect?: readonly string[];
+    readonly exclude?: readonly string[];
+    readonly maxLines?: number;
+    readonly maxBytes?: number;
+    readonly lsEntries?: number;
+    readonly findResults?: number;
+    readonly grepMatches?: number;
+    readonly grepLineChars?: number;
+    readonly grepEngine?: "auto" | "ripgrep" | "builtin";
+    readonly grepTimeoutMs?: number;
+    readonly grepIgnoreFiles?: boolean;
+    readonly maxFileBytes?: number;
+    readonly readImages?: boolean;
+    readonly imageMaxSide?: number;
+    readonly fuzzyEdit?: boolean;
+    readonly bashTimeoutMs?: number;
+    readonly bashMaxTimeoutMs?: number;
+    readonly bashEnv?: {
+        readonly [x: string]: string | undefined;
+    };
+    readonly bashInheritEnv?: boolean;
+    readonly bashEnvAllow?: readonly string[];
+    readonly bashSessionEnv?: boolean;
+    readonly spillDir?: string | null;
+    readonly spillKeep?: number;
+    readonly progressMs?: number;
+    readonly environmentSection?: boolean;
+    readonly sectionOrder?: number;
+} | undefined) => Layer.Layer<Capabilities, import("@xandreed/core").HarnessError, never>;
+/** Optional CLI image fitting on the host's matching Bash and FileSystem. @public */
+export declare const imageResizerPlugin: import("@xandreed/core").TypedPlugin<{
+    readonly tool: "auto" | "magick" | "convert" | "vips" | "sips";
+    readonly tempDir: string | null;
+    readonly timeoutMs: number;
+    readonly maxSourcePixels: number;
+}, {
+    readonly tool: "auto" | "magick" | "convert" | "vips" | "sips";
+    readonly tempDir: string | null;
+    readonly timeoutMs: number;
+    readonly maxSourcePixels: number;
+}, ImageResizer, import("@xandreed/core").HarnessError, FileSystem | Bash>;
+/** @public */
+export declare const ImageResizerPluginLive: (options?: {
+    readonly tool?: "auto" | "magick" | "convert" | "vips" | "sips";
+    readonly tempDir?: string | null;
+    readonly timeoutMs?: number;
+    readonly maxSourcePixels?: number;
+} | undefined) => Layer.Layer<ImageResizer, import("@xandreed/core").HarnessError, FileSystem | Bash>;

package/dist/plugin.adapter.js

@@ -0,0 +1,38 @@
+import { Effect, Layer } from "effect";
+import { Bash, Capabilities, definePlugin, FileSystem, ImageResizer, SessionEnvironment } from "@xandreed/core";
+import { BashLive } from "./bash.adapter.js";
+import { FileSystemLive } from "./file-system.adapter.js";
+import { LocalSystemConfig, localSystemDefaults } from "./local-system.entity.js";
+import { ImageResizerCliLive } from "./image-resizer.adapter.js";
+import { ImageResizerConfig, imageResizerDefaults } from "./image-resizer.entity.js";
+import { workspaceTools } from "./workspace-tools.adapter.js";
+import { WorkspaceToolsConfig, workspaceToolsDefaults } from "./workspace-tools.entity.js";
+export const localSystemPlugin = definePlugin({
+  id: "@xandreed/plugin-workspace/local",
+  version: "0.15.0",
+  scope: "runtime",
+  config: LocalSystemConfig,
+  defaults: localSystemDefaults,
+  provides: [FileSystem, Bash],
+  layer: (config) => Layer.merge(FileSystemLive, BashLive(config))
+}), LocalSystemPluginLive = localSystemPlugin.live, workspaceToolsPlugin = definePlugin({
+  id: "@xandreed/plugin-workspace/tools",
+  version: "0.15.0",
+  scope: "runtime",
+  config: WorkspaceToolsConfig,
+  defaults: workspaceToolsDefaults,
+  requires: [FileSystem, SessionEnvironment],
+  optional: [Bash, ImageResizer],
+  provides: [],
+  contributes: [Capabilities],
+  layer: (config) => Layer.effect(Capabilities, workspaceTools(config).pipe(Effect.map((capability) => [capability])))
+}), WorkspaceToolsPluginLive = workspaceToolsPlugin.live, imageResizerPlugin = definePlugin({
+  id: "@xandreed/plugin-workspace/images",
+  version: "0.15.0",
+  scope: "runtime",
+  config: ImageResizerConfig,
+  defaults: imageResizerDefaults,
+  requires: [FileSystem, Bash],
+  provides: [ImageResizer],
+  layer: (config) => ImageResizerCliLive(config)
+}), ImageResizerPluginLive = imageResizerPlugin.live;

package/dist/read-tools.adapter.d.ts

@@ -0,0 +1,39 @@
+import type { Path, RcMap, Semaphore } from "effect";
+import { Failure, FileSystem, SessionEnvironment } from "@xandreed/core";
+import type { RegisteredTool, Subject } from "@xandreed/core";
+import type { ProtectRule } from "./workspace-path.entity.functions.js";
+import type { WorkspaceToolsConfig } from "./workspace-tools.entity.js";
+/** What every workspace tool is built with: the configuration, the path functions, the compiled `protect` globs and the per-file write locks. */
+export interface WorkspaceToolContext {
+    readonly config: WorkspaceToolsConfig;
+    readonly path: Path.Path;
+    readonly protect: ReadonlyArray<ProtectRule>;
+    readonly locks: RcMap.RcMap<string, Semaphore.Semaphore>;
+    readonly resizesImages: boolean;
+}
+/** The services every workspace tool reads on each call, and the `workspace.environment` section on each render: the file system, and the session's workspace on it (`bash` reads `Bash` too). */
+export declare const WORKSPACE_SERVICES: readonly [typeof FileSystem, typeof SessionEnvironment];
+export declare const failure: (error: string, message: string) => Failure;
+/** The refusal of a path that is neither a regular file nor a directory: reading a pipe, socket or device could wait forever. */
+export declare const notAFile: (display: string, tool: string) => Failure;
+/** A file the result names, for memory to keep track of; none for a name memory could not store as an id. */
+export declare const fileSubjects: (path: string) => ReadonlyArray<Subject>;
+/** `read`: a window of a text file's lines, an image (`readImages`), or what a binary file is. */
+export declare const readTool: ({ config, path, resizesImages }: WorkspaceToolContext) => RegisteredTool;
+/** `ls`: a directory's entries by name, at most `lsEntries` of them. */
+export declare const lsTool: ({ config, path }: WorkspaceToolContext) => RegisteredTool;
+/** `find`: the files under a directory whose path matches a glob, as paths relative to the workspace root. */
+export declare const findTool: ({ config, path }: WorkspaceToolContext) => RegisteredTool;
+/**
+ * `grep`: the lines of the files under a path (or of one file) that match.
+ * Files come from a walk that never enters links or excluded names; each is
+ * resolved again before it is read and skipped when it leads outside the
+ * workspace, is not a regular file, is larger than `maxFileBytes` or is
+ * binary; one the file system refuses (permission denied, say) is named in
+ * `unreadable` with the reason, not counted as skipped. Lines are cut to `grepLineChars` before matching. Searching a
+ * directory, one file gives at most a quarter of the limit, so one large
+ * file cannot fill the result, however many files the directory holds (as
+ * with ripgrep, which cannot know that ahead). A pattern with a line break
+ * is refused (`singleLinePattern`) whichever engine runs.
+ */
+export declare const grepTool: ({ config, path }: WorkspaceToolContext) => RegisteredTool;

package/dist/read-tools.adapter.js

@@ -0,0 +1,109 @@
+import { Tool } from "effect/ai";
+import { Effect, Option, Result } from "effect";
+import { Bash, defineTool, Failure, FileSystem, ImageResizer, SessionEnvironment, SubjectId } from "@xandreed/core";
+import { searchRipgrep } from "./ripgrep.adapter.js";
+import { compilePattern, searchText, singleLinePattern } from "./text-search.entity.functions.js";
+import { decodeText, formatBytes, lineWindow, looksBinary, mediaTypeOf } from "./text-window.entity.functions.js";
+import { displayOf, excludesBelow, fsFailure, isWithin, openWorkspace, resolveTarget, withinAnyRoot } from "./workspace-path.entity.functions.js";
+import { FindResult, GrepResult, LsResult, ReadResult } from "./workspace-tools.entity.js";
+import { binaryRead, compactFind, fileTooLargeHint, compactGrep, compactLs, compactRead, readMedia, renderFind, renderGrep, renderLs, renderRead, toolDescriptions, toolParameters } from "./workspace-tools.entity.functions.js";
+export const WORKSPACE_SERVICES = [FileSystem, SessionEnvironment], failure = (error, message) => ({ error, message }), notAFile = (display, tool) => failure("NotAFile", `${display} is not a regular file (a pipe, socket or device); ${tool} works on regular files only, use bash for it`);
+const walkExcludes = (access, target, excludes) => excludesBelow(excludes, isWithin(access.root, target.path) ? Option.some(access.path.relative(access.root, target.path)) : Option.none());
+export const fileSubjects = (path) => path.length > 0 && path.trim() === path ? [{ kind: "file", id: SubjectId.make(path), label: Option.none(), data: Option.none() }] : [];
+const ReadTool = (config, resizesImages) => Tool.make("read", { description: toolDescriptions(config, resizesImages).read, parameters: toolParameters(config).read, success: ReadResult, failure: Failure, failureMode: "return" }), LsTool = (config) => Tool.make("ls", { description: toolDescriptions(config).ls, parameters: toolParameters(config).ls, success: LsResult, failure: Failure, failureMode: "return" }), FindTool = (config) => Tool.make("find", { description: toolDescriptions(config).find, parameters: toolParameters(config).find, success: FindResult, failure: Failure, failureMode: "return" }), GrepTool = (config) => Tool.make("grep", { description: toolDescriptions(config).grep, parameters: toolParameters(config).grep, success: GrepResult, failure: Failure, failureMode: "return" });
+export const readTool = ({ config, path, resizesImages }) => defineTool({
+  tool: ReadTool(config, resizesImages),
+  requires: resizesImages ? [...WORKSPACE_SERVICES, ImageResizer] : WORKSPACE_SERVICES,
+  handler: (params) => Effect.gen(function* () {
+    const access = yield* openWorkspace(path, config), target = yield* resolveTarget(access, params.path, { confine: config.confine }), info = yield* access.fs.stat(target.path).pipe(Effect.mapError(fsFailure(target.display)));
+    if (info.kind === "directory")
+      return yield* Effect.fail(failure("IsDirectory", `${target.display} is a directory; use ls to list it`));
+    if (info.kind !== "file")
+      return yield* Effect.fail(notAFile(target.display, "read"));
+    if (info.size > config.maxFileBytes)
+      return yield* Effect.fail(failure("FileTooLarge", `${target.display} is ${formatBytes(info.size)}, more than the ${formatBytes(config.maxFileBytes)} read loads; ${fileTooLargeHint(target.display, config.readImages)}`));
+    const bytes = yield* access.fs.readBytes(target.path).pipe(Effect.mapError(fsFailure(target.display)));
+    if (looksBinary(bytes))
+      return yield* binaryRead(target.display, bytes, config.readImages, Option.getOrNull(mediaTypeOf(target.display)), resizesImages ? Option.map(yield* Effect.serviceOption(ImageResizer), (resizer) => resizer.fit) : Option.none(), config.imageMaxSide);
+    const decoded = decodeText(bytes), window = lineWindow(decoded.text, { offset: params.offset ?? 1, limit: params.limit ?? config.maxLines, maxBytes: config.maxBytes });
+    return yield* Result.match(window, {
+      onFailure: (total) => Effect.fail(failure("OffsetPastEnd", `${target.display} has ${total} line${total === 1 ? "" : "s"}; offset must be at most ${Math.max(1, total)}`)),
+      onSuccess: (lines) => Effect.succeed({
+        _tag: "Text",
+        path: target.display,
+        text: lines.lines.join(`
+`),
+        firstLine: lines.firstLine,
+        lastLine: lines.lastLine,
+        totalLines: lines.totalLines,
+        next: Option.getOrNull(lines.next),
+        clipped: lines.clipped,
+        lossy: decoded.lossy
+      })
+    });
+  }),
+  view: { version: "3", render: renderRead, compact: compactRead, subjects: (result) => fileSubjects(result.path), media: readMedia },
+  annotations: { readOnly: !0 }
+}), lsTool = ({ config, path }) => defineTool({
+  tool: LsTool(config),
+  requires: WORKSPACE_SERVICES,
+  handler: (params) => Effect.gen(function* () {
+    const access = yield* openWorkspace(path, config), target = yield* resolveTarget(access, params.path ?? ".", { confine: config.confine }), entries = yield* access.fs.list(target.path).pipe(Effect.mapError((error) => error.reason === "NotDirectory" ? failure("NotDirectory", `${target.display} is not a directory; use read to see a file`) : fsFailure(target.display)(error))), limit = params.limit ?? config.lsEntries;
+    return { path: target.display, entries: entries.slice(0, limit).map((entry) => ({ name: entry.name, kind: entry.kind })), total: entries.length };
+  }),
+  view: { version: "2", render: renderLs, compact: compactLs },
+  annotations: { readOnly: !0 }
+}), findTool = ({ config, path }) => defineTool({
+  tool: FindTool(config),
+  requires: WORKSPACE_SERVICES,
+  handler: (params) => Effect.gen(function* () {
+    const access = yield* openWorkspace(path, config), target = yield* resolveTarget(access, params.path ?? ".", { confine: config.confine }), limit = params.limit ?? config.findResults, found = yield* access.fs.glob(params.pattern, { cwd: target.path, exclude: walkExcludes(access, target, config.exclude), dot: !0, onlyFiles: !0, limit }).pipe(Effect.mapError((error) => error.reason === "Invalid" ? failure("InvalidPattern", `${params.pattern}: ${error.message}`) : fsFailure(target.display)(error)));
+    return { pattern: params.pattern, path: target.display, paths: found.paths.map((relative) => displayOf(access, access.path.join(target.path, relative))), truncated: found.truncated };
+  }),
+  view: { version: "2", render: (result) => renderFind(result, config.maxLines, config.maxBytes), compact: compactFind },
+  annotations: { readOnly: !0 }
+}), grepTool = ({ config, path }) => defineTool({
+  tool: GrepTool(config),
+  requires: config.grepEngine === "ripgrep" ? [...WORKSPACE_SERVICES, Bash] : WORKSPACE_SERVICES,
+  handler: (params) => Effect.gen(function* () {
+    const access = yield* openWorkspace(path, config), target = yield* resolveTarget(access, params.path ?? ".", { confine: config.confine });
+    yield* Effect.fromResult(singleLinePattern(params.pattern));
+    const pattern = config.grepEngine === "ripgrep" ? Option.none() : Option.some(yield* Effect.fromResult(compilePattern(params.pattern, { literal: params.literal ?? !1, ignoreCase: params.ignoreCase ?? !1 }))), info = yield* access.fs.stat(target.path).pipe(Effect.mapError(fsFailure(target.display)));
+    if (info.kind !== "file" && info.kind !== "directory")
+      return yield* Effect.fail(notAFile(target.display, "grep"));
+    if (config.grepEngine === "ripgrep")
+      return yield* searchRipgrep(access, target, info.kind === "directory", params, config);
+    const glob = params.glob === void 0 ? "**/*" : params.glob.includes("/") ? params.glob : `**/${params.glob}`, files = info.kind === "file" ? [{ path: target.path, display: target.display }] : yield* access.fs.glob(glob, { cwd: target.path, exclude: walkExcludes(access, target, config.exclude), dot: !0, onlyFiles: !0 }).pipe(Effect.map((found) => found.paths.map((relative) => {
+      const absolute = access.path.join(target.path, relative);
+      return { path: absolute, display: displayOf(access, absolute) };
+    })), Effect.mapError((error) => error.reason === "Invalid" ? failure("InvalidPattern", `glob ${params.glob ?? glob}: ${error.message}`) : fsFailure(target.display)(error))), limit = params.limit ?? config.grepMatches, perFile = info.kind === "directory" ? Math.max(1, Math.ceil(limit / 4)) : limit, context = params.context ?? 0, skip = (state) => ({ ...state, skipped: state.skipped + 1 }), searched = yield* Effect.reduce(files, () => ({ lines: [], matches: 0, files: 0, skipped: 0, truncated: !1, unreadable: [] }), (state, file) => {
+      if (state.matches >= limit)
+        return Effect.succeed({ ...state, truncated: !0 });
+      return Effect.gen(function* () {
+        const real = yield* access.fs.realPath(file.path);
+        if (config.confine && !withinAnyRoot(access, real))
+          return Option.none();
+        const found = yield* access.fs.stat(real);
+        if (found.kind !== "file" || found.size > config.maxFileBytes)
+          return Option.none();
+        const bytes = yield* access.fs.readBytes(real);
+        return looksBinary(bytes) ? Option.none() : Option.some(bytes);
+      }).pipe(Effect.map(Option.match({
+        onNone: () => skip(state),
+        onSome: (content) => {
+          const found = searchText(decodeText(content).text, Option.getOrThrow(pattern), { lineChars: config.grepLineChars, context, cap: Math.min(perFile, limit - state.matches) });
+          return {
+            ...state,
+            lines: [...state.lines, ...found.lines.map((line) => ({ path: file.display, ...line }))],
+            matches: state.matches + found.matches,
+            files: state.files + (found.matches > 0 ? 1 : 0),
+            truncated: state.truncated || found.capped
+          };
+        }
+      })), Effect.catch((error) => Effect.succeed({ ...state, unreadable: [...state.unreadable, { path: file.display, reason: error.reason }] })));
+    });
+    return { pattern: params.pattern, path: target.display, ...searched, timedOut: !1 };
+  }),
+  view: { version: "4", render: (result, params) => renderGrep(result, (params.context ?? 0) > 0, config.maxLines, config.maxBytes), compact: compactGrep },
+  annotations: { readOnly: !0 }
+});

package/dist/ripgrep.adapter.d.ts

@@ -0,0 +1,74 @@
+import { Effect } from "effect";
+import { Bash } from "@xandreed/core";
+import type { WorkspaceAccess } from "./workspace-path.entity.functions.js";
+/** A bounded, interruptible search on the same machine as the Bash/FileSystem pair. */
+export declare const searchRipgrep: (access: WorkspaceAccess, target: {
+    readonly path: string;
+    readonly display: string;
+}, directory: boolean, params: {
+    readonly pattern: string;
+    readonly path?: string;
+    readonly limit?: number;
+    readonly context?: number;
+    readonly literal?: boolean;
+    readonly glob?: string;
+    readonly ignoreCase?: boolean;
+}, config: {
+    readonly tools: readonly ("find" | "write" | "read" | "grep" | "bash" | "ls" | "edit")[];
+    readonly always: readonly ("read" | "edit" | "shell")[];
+    readonly confine: boolean;
+    readonly workspaceAccess: "write" | "read";
+    readonly roots: readonly {
+        readonly path: string;
+        readonly access: "write" | "read";
+    }[];
+    readonly protect: readonly string[];
+    readonly exclude: readonly string[];
+    readonly maxLines: number;
+    readonly maxBytes: number;
+    readonly lsEntries: number;
+    readonly findResults: number;
+    readonly grepMatches: number;
+    readonly grepLineChars: number;
+    readonly grepEngine: "auto" | "ripgrep" | "builtin";
+    readonly grepTimeoutMs: number;
+    readonly grepIgnoreFiles: boolean;
+    readonly maxFileBytes: number;
+    readonly readImages: boolean;
+    readonly imageMaxSide: number;
+    readonly fuzzyEdit: boolean;
+    readonly bashTimeoutMs: number;
+    readonly bashMaxTimeoutMs: number;
+    readonly bashEnv: {
+        readonly [x: string]: string;
+    };
+    readonly bashInheritEnv: boolean;
+    readonly bashEnvAllow: readonly string[];
+    readonly bashSessionEnv: boolean;
+    readonly spillDir: string | null;
+    readonly spillKeep: number;
+    readonly progressMs: number;
+    readonly environmentSection: boolean;
+    readonly sectionOrder: number;
+}) => Effect.Effect<{
+    pattern: string;
+    path: string;
+    lines: readonly {
+        readonly path: string;
+        readonly line: number;
+        readonly text: string;
+        readonly match: boolean;
+    }[];
+    matches: number;
+    files: number;
+    skipped: number;
+    truncated: boolean;
+    unreadable: {
+        path: string;
+        reason: "Invalid" | "NotFound" | "Exists" | "IsDirectory" | "NotDirectory" | "NotEmpty" | "Permission" | "Io";
+    }[];
+    timedOut: boolean;
+}, {
+    readonly error: string;
+    readonly message: string;
+}, Bash>;