@xandreed/plugin-workspace 0.14.0 → 0.15.0

package/dist/workspace-path.entity.functions.js

@@ -2,38 +2,63 @@ import { Effect, Option, Result } from "effect";
 import { compileGlob, FileSystem, FsError, SessionEnvironment } from "@xandreed/core";
 const failure = (error, message) => ({ error, message }), reasons = {
   NotFound: (display) => failure("NotFound", `${display} does not exist`),
-  IsDirectory: (display) => failure("IsDirectory", `${display} is a directory`),
+  Exists: (display) => failure("AlreadyExists", `${display} already exists, and the file system would not replace it; give another path`),
+  IsDirectory: (display) => failure("IsDirectory", `${display} is a directory; give the path of a file`),
   NotDirectory: (display) => failure("NotDirectory", `${display} is not a directory, or a part of the path before it is a file`),
-  Permission: (display) => failure("Permission", `permission denied: ${display}`)
+  NotEmpty: (display) => failure("DirectoryNotEmpty", `${display} is a directory with entries in it; give another path`),
+  Permission: (display) => failure("AccessDenied", `permission denied: ${display}`),
+  Invalid: (display) => failure("InvalidPath", `${display} is not a path the file system accepts; check it and try again`),
+  Io: (display) => failure("FileSystemError", `${display} could not be read or written (a file-system error); try again, or give another path`)
 };
-export const fsFailure = (display) => (error) => reasons[error.reason]?.(display) ?? failure(error.reason, `${display}: ${error.message}`), isWithin = (root, path) => path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`), openWorkspace = (path) => Effect.gen(function* () {
-  const fs = yield* FileSystem, { workspace } = yield* SessionEnvironment, lexicalRoot = path.resolve(workspace), root = yield* fs.realPath(lexicalRoot).pipe(Effect.mapError((error) => failure("WorkspaceMissing", `the workspace directory cannot be opened (${error.reason}): ${error.message}`)));
-  return { fs, path, root, lexicalRoot };
-}), displayOf = (access, absolute) => {
+export const fsFailure = (display) => (error) => reasons[error.reason](display);
+const unopenable = {
+  NotFound: "does not exist",
+  NotDirectory: "is not a directory",
+  Permission: "cannot be opened for lack of permission",
+  Invalid: "is not a path the file system accepts",
+  Exists: "cannot be opened because of a file-system error",
+  IsDirectory: "cannot be opened because of a file-system error",
+  NotEmpty: "cannot be opened because of a file-system error",
+  Io: "cannot be opened because of a file-system error"
+};
+export const workspaceMissing = (reason) => failure("WorkspaceMissing", `the workspace directory ${unopenable[reason]}, so no workspace tool can run in this session; tell the user`), isWithin = (root, path) => path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`), openWorkspace = Effect.fnUntraced(function* (path, options = { roots: [], workspaceAccess: "write" }) {
+  const fs = yield* FileSystem, { workspace } = yield* SessionEnvironment, lexicalRoot = path.resolve(workspace), root = yield* fs.realPath(lexicalRoot).pipe(Effect.mapError((error) => workspaceMissing(error.reason))), extra = yield* Effect.forEach(options.roots, (allowed) => {
+    const lexicalRoot = path.resolve(root, allowed.path);
+    return fs.realPath(lexicalRoot).pipe(Effect.flatMap((root) => fs.stat(root).pipe(Effect.flatMap((info) => info.kind === "directory" ? Effect.succeed(Option.some({ root, lexicalRoot, access: allowed.access })) : Effect.logWarning("an extra workspace root is not a directory", { path: allowed.path }).pipe(Effect.as(Option.none()))))), Effect.catch((error) => Effect.logWarning("an extra workspace root could not be opened", { path: allowed.path, reason: error.reason }).pipe(Effect.as(Option.none()))));
+  }, { concurrency: 1 });
+  return { fs, path, root, lexicalRoot, roots: [{ root, lexicalRoot, access: options.workspaceAccess }, ...extra.flatMap(Option.toArray)] };
+}), withinAnyRoot = (access, path) => access.roots.some((root) => isWithin(root.root, path));
+const folded = (path) => path.normalize("NFC").toLowerCase(), rootOf = (access, path, fold = (same) => same) => access.roots.reduce((selected, candidate) => isWithin(fold(candidate.root), fold(path)) && Option.match(selected, { onNone: () => !0, onSome: (current) => candidate.root.length >= current.root.length }) ? Option.some(candidate) : selected, Option.none()), readOnlyRootOf = (access, path) => Option.orElse(Option.filter(rootOf(access, path), (root) => root.access === "read"), () => Option.filter(rootOf(access, path, folded), (root) => root.access === "read"));
+export const displayOf = (access, absolute) => {
   const base = isWithin(access.root, absolute) ? access.root : isWithin(access.lexicalRoot, absolute) ? access.lexicalRoot : void 0;
   if (base === void 0)
     return absolute;
   const relative = access.path.relative(base, absolute);
   return relative === "" ? "." : relative;
 };
-const canonicalOf = (access, target) => access.fs.realPath(target).pipe(Effect.catchIf((error) => error.reason === "NotFound", (missing) => {
+const canonicalOf = (access, target, display) => access.fs.realPath(target).pipe(Effect.catch((error) => {
   const parent = access.path.dirname(target);
-  if (parent === target)
-    return Effect.fail(missing);
+  if (error.reason !== "NotFound" || parent === target)
+    return Effect.fail(fsFailure(display)(error));
   return access.fs.stat(target, { followSymlinks: !1 }).pipe(Effect.matchEffect({
-    onSuccess: () => Effect.fail(new FsError({ path: target, reason: "Invalid", message: "it is a symbolic link to something that does not exist" })),
-    onFailure: (error) => error.reason === "NotFound" ? canonicalOf(access, parent).pipe(Effect.map((dir) => access.path.join(dir, access.path.basename(target)))) : Effect.fail(error)
+    onSuccess: () => Effect.fail(failure("BrokenSymlink", `${display}: it is a symbolic link to something that does not exist`)),
+    onFailure: (missing) => missing.reason === "NotFound" ? canonicalOf(access, parent, display).pipe(Effect.map((dir) => access.path.join(dir, access.path.basename(target)))) : Effect.fail(fsFailure(display)(missing))
   }));
 }));
-export const resolveTarget = (access, input, options) => Effect.gen(function* () {
-  const lexical = access.path.resolve(access.root, input.length === 0 ? "." : input), display = displayOf(access, lexical), inside = (path) => isWithin(access.root, path) || isWithin(access.lexicalRoot, path);
+export const resolveTarget = Effect.fnUntraced(function* (access, input, options) {
+  const lexical = access.path.resolve(access.root, input.length === 0 ? "." : input), display = displayOf(access, lexical), inside = (path) => access.roots.some((root) => isWithin(root.root, path) || isWithin(root.lexicalRoot, path)), extras = access.roots.slice(1).map((root) => displayOf(access, root.root));
   if (options.confine && !inside(lexical))
-    return yield* Effect.fail(failure("OutsideWorkspace", `${input} is outside the workspace; use a path under its root`));
-  const path = yield* canonicalOf(access, lexical).pipe(Effect.mapError(fsFailure(display)));
-  if (options.confine && !isWithin(access.root, path))
-    return yield* Effect.fail(failure("OutsideWorkspace", `${display} leads outside the workspace through a symbolic link`));
+    return yield* Effect.fail(failure("OutsideWorkspace", extras.length === 0 ? `${input} is outside the workspace; use a path under its root` : `${input} is outside the workspace and its allowed roots (${extras.join(", ")}); use a path under one of them`));
+  const path = yield* canonicalOf(access, lexical, display);
+  if (options.confine && !withinAnyRoot(access, path))
+    return yield* Effect.fail(failure("OutsideWorkspace", extras.length === 0 ? `${display} leads outside the workspace through a symbolic link` : `${display} leads outside the workspace and its allowed roots (${extras.join(", ")}) through a symbolic link`));
+  const readOnly = options.confine && options.intent === "write" ? readOnlyRootOf(access, path) : Option.none();
+  if (Option.isSome(readOnly)) {
+    const place = readOnly.value.root === access.root ? "the workspace root" : displayOf(access, readOnly.value.root);
+    return yield* Effect.fail(failure("ReadOnly", `${display} is under ${place}, which the workspace tools may read but not change`));
+  }
   return { path, display };
-}), compileProtect = (globs) => Result.all(globs.map((glob) => Result.mapError(Result.map(compileGlob(glob, { dot: !0 }), (matcher) => ({ glob, matches: matcher.matches })), (reason) => `protect glob ${glob} is not usable: ${reason}`)));
+}), compileProtect = (globs) => Result.all(globs.map((glob) => Result.mapError(Result.flatMap(compileGlob(glob, { dot: !0 }), (exact) => Result.map(compileGlob(folded(glob), { dot: !0 }), (caseless) => ({ glob, matches: (relative) => exact.matches(relative) || caseless.matches(folded(relative)) }))), (reason) => `protect glob ${glob} is not usable: ${reason}`)));
 const segmentsOf = (glob) => glob.split("/").filter((segment) => segment.length > 0 && segment !== "."), ownBraces = (segment) => (segment.match(/\{/g) ?? []).length === (segment.match(/\}/g) ?? []).length, remainderBelow = (pattern, names) => {
   const [head, ...rest] = pattern, [name, ...below] = names;
   if (name === void 0)

package/dist/workspace-path.entity.js

@@ -1,8 +1,9 @@
 import { Schema } from "effect";
-export const WorkspaceTarget = Schema.Struct({
+export const WorkspaceAccessMode = Schema.Literals(["read", "write"]), WorkspaceAllowedRoot = Schema.Struct({ path: Schema.NonEmptyString, access: WorkspaceAccessMode }), AllowedRoot = Schema.Struct({ root: Schema.String, lexicalRoot: Schema.String, access: WorkspaceAccessMode }), WorkspaceTarget = Schema.Struct({
   path: Schema.String,
   display: Schema.String
 }), WorkspaceRoot = Schema.Struct({
   root: Schema.String,
-  lexicalRoot: Schema.String
+  lexicalRoot: Schema.String,
+  roots: Schema.Array(AllowedRoot)
 });

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

@@ -2,14 +2,14 @@ import { Effect } from "effect";
 import type { Scope } from "effect";
 import { HarnessError } from "@xandreed/core";
 import type { Capability } from "@xandreed/core";
-import type { WorkspaceToolsConfig } from "./workspace-tools.entity.js";
 /**
  * The workspace tools as one capability, for the workspace in each call's
  * `SessionEnvironment`, over each call's `FileSystem` and `Bash`: `read`,
  * `ls`, `find` and `grep` (skill `workspace.read`, read-only), `write` and
  * `edit` (`workspace.edit`, needing `fs.write`) and `bash`
  * (`workspace.shell`, needing `shell.exec`), plus the
- * `workspace.environment` prompt section. Built once (in a scope, which
+ * `workspace.environment` prompt section, which reads the same services as
+ * the tools, where the turn renders it. Built once (in a scope, which
  * holds the per-file write locks): `bash` and its skill are left out, with
  * a warning, when there is no `Bash` service here; `protect` and `exclude`
  * globs that do not compile fail with `config.options` (through the plugin,
@@ -17,5 +17,50 @@ import type { WorkspaceToolsConfig } from "./workspace-tools.entity.js";
  * decoded, so a graph refuses them before activating anything). Tools are never
  * given guidance as skill instructions: it is in their descriptions and the
  * section, since an always-on skill's instructions never reach the model.
+ * Ripgrep requires FileSystem and Bash to see the same file tree, so
+ * `grepEngine: "auto"` uses it only when both, here, are this machine's
+ * (`localFileSystem` and a `makeBash` shell, as `localSystemPlugin`
+ * provides); with any other pair (an in-memory file system, a container's
+ * shell, a wrapper) it selects builtin without probing. A host whose pair
+ * shares a tree selects `ripgrep` itself.
+ *
+ * @public
  */
-export declare const workspaceTools: (config: WorkspaceToolsConfig) => Effect.Effect<Capability, HarnessError, Scope.Scope>;
+export declare const workspaceTools: (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<Capability, HarnessError, Scope.Scope>;

package/dist/workspace-tools.adapter.js

@@ -1,10 +1,12 @@
 import { Effect, Option, Path, RcMap, Result, Semaphore } from "effect";
-import { Bash, compileGlob, defineCapability, defineSkill, HarnessError, SessionEnvironment } from "@xandreed/core";
+import { Bash, compileGlob, defineCapability, definePromptSection, defineSkill, FileSystem, HarnessError, ImageResizer, SessionEnvironment } from "@xandreed/core";
+import { runsOnThisMachine } from "./bash.adapter.js";
 import { bashTool } from "./bash-tool.adapter.js";
-import { findTool, grepTool, lsTool, readTool } from "./read-tools.adapter.js";
+import { localFileSystem } from "./file-system.adapter.js";
+import { findTool, grepTool, lsTool, readTool, WORKSPACE_SERVICES } from "./read-tools.adapter.js";
 import { compileProtect, openWorkspace } from "./workspace-path.entity.functions.js";
 import { WORKSPACE_PERMISSIONS } from "./workspace-tools.entity.js";
-import { environmentText, skillOfTool } from "./workspace-tools.entity.functions.js";
+import { bashEnvironment, environmentText, skillOfTool } from "./workspace-tools.entity.functions.js";
 import { editTool, writeTool } from "./write-tools.adapter.js";
 const ORDER = ["read", "ls", "find", "grep", "write", "edit", "bash"], builders = {
   read: readTool,
@@ -19,20 +21,32 @@ const ORDER = ["read", "ls", "find", "grep", "write", "edit", "bash"], builders
   edit: { id: "workspace.edit", summary: "Create and change files in the workspace (write, edit).", permissions: [WORKSPACE_PERMISSIONS.write] },
   shell: { id: "workspace.shell", summary: "Run shell commands in the workspace (bash).", permissions: [WORKSPACE_PERMISSIONS.exec] }
 }, invalid = (message) => new HarnessError({ code: "config.options", plugin: "@xandreed/plugin-workspace/tools", message });
-export const workspaceTools = (config) => Effect.gen(function* () {
+export const workspaceTools = Effect.fnUntraced(function* (config) {
   const path = yield* Effect.service(Path.Path).pipe(Effect.provide(Path.layer)), protect = yield* Effect.fromResult(compileProtect(config.protect)).pipe(Effect.mapError(invalid)), badExclude = config.exclude.find((glob) => Result.isFailure(compileGlob(glob, { dot: !0 })));
   if (badExclude !== void 0)
     return yield* Effect.fail(invalid(`exclude glob ${badExclude} is not usable`));
-  const locks = yield* RcMap.make({ lookup: (_path) => Semaphore.make(1), idleTimeToLive: "1 minute" }), hasBash = Option.isSome(yield* Effect.serviceOption(Bash)), wanted = ORDER.filter((tool) => config.tools.includes(tool));
+  const locks = yield* RcMap.make({ lookup: (_path) => Semaphore.make(1), idleTimeToLive: "1 minute" }), bash = yield* Effect.serviceOption(Bash), hasBash = Option.isSome(bash), sameTree = Option.exists(yield* Effect.serviceOption(FileSystem), (service) => service === localFileSystem) && Option.exists(bash, runsOnThisMachine);
+  if (config.tools.includes("grep") && config.grepEngine === "auto" && !sameTree)
+    yield* Effect.logDebug("grep: the FileSystem and Bash are not this machine's local pair; using the builtin engine");
+  const probe = config.tools.includes("grep") && (config.grepEngine === "ripgrep" || config.grepEngine === "auto" && sameTree) ? yield* Option.match(bash, {
+    onNone: () => Effect.succeed(!1),
+    onSome: (service) => service.exec("rg --version", { cwd: "/", timeoutMs: 5000, ...bashEnvironment(config, Option.none()) }).pipe(Effect.map((result) => result.termination === "exit" && Option.contains(result.exitCode, 0)), Effect.catch((error) => Effect.logDebug("grep: ripgrep probe failed", error).pipe(Effect.as(!1))))
+  }) : !1;
+  if (config.tools.includes("grep") && config.grepEngine === "ripgrep" && !probe)
+    return yield* Effect.fail(invalid("grepEngine ripgrep requires rg on the Bash service PATH"));
+  if (config.tools.includes("grep") && config.grepEngine === "auto" && sameTree && !probe)
+    yield* Effect.logDebug("grep: ripgrep is unavailable; using the builtin engine");
+  const resolved = { ...config, grepEngine: probe ? "ripgrep" : "builtin" }, wanted = ORDER.filter((tool) => config.tools.includes(tool));
   if (wanted.includes("bash") && !hasBash)
     yield* Effect.logWarning("@xandreed/plugin-workspace/tools: there is no Bash service, so the bash tool and the workspace.shell skill are left out (add localSystemPlugin, or a Bash, to have them)");
-  const enabled = wanted.filter((tool) => tool !== "bash" || hasBash), context = { config, path, protect, locks }, section = {
+  const enabled = wanted.filter((tool) => tool !== "bash" || hasBash), context = { config: resolved, path, protect, locks, resizesImages: config.readImages && Option.isSome(yield* Effect.serviceOption(ImageResizer)) }, section = definePromptSection({
     id: "workspace.environment",
-    version: "1",
+    version: "3",
     tier: "session",
     order: config.sectionOrder,
-    render: () => openWorkspace(path).pipe(Effect.map((access) => access.root), Effect.catch(() => SessionEnvironment.pipe(Effect.map((environment) => path.resolve(environment.workspace)))), Effect.map((root) => Option.some(environmentText(root, config, enabled))))
-  };
+    requires: WORKSPACE_SERVICES,
+    render: () => openWorkspace(path).pipe(Effect.map((access) => access.root), Effect.catch(() => SessionEnvironment.pipe(Effect.map((environment) => path.resolve(environment.workspace)))), Effect.map((root) => Option.some(environmentText(root, resolved, enabled))))
+  });
   return defineCapability({
     id: "@xandreed/plugin-workspace/tools",
     version: "1",

package/dist/workspace-tools.entity.d.ts

@@ -1,31 +1,47 @@
 import { Schema } from "effect";
-/** The seven workspace tools, by the names the model calls them. */
+/**
+ * The seven workspace tools, by the names the model calls them.
+ *
+ * @public
+ */
 export declare const WorkspaceToolName: Schema.Literals<readonly ["read", "write", "edit", "ls", "find", "grep", "bash"]>;
 export type WorkspaceToolName = typeof WorkspaceToolName.Type;
 /**
  * The tools' three skills, by the short names `always` takes: `read`
  * (`workspace.read`: read, ls, find, grep), `edit` (`workspace.edit`: write,
  * edit) and `shell` (`workspace.shell`: bash).
+ *
+ * @public
  */
 export declare const WorkspaceSkillName: Schema.Literals<readonly ["read", "edit", "shell"]>;
 export type WorkspaceSkillName = typeof WorkspaceSkillName.Type;
-/** The grants the tools that change things need: `write` and `edit` need `fs.write`, `bash` needs `shell.exec`. */
+/**
+ * The grants the tools that change things need: `write` and `edit` need `fs.write`, `bash` needs `shell.exec`.
+ *
+ * @public
+ */
 export declare const WORKSPACE_PERMISSIONS: {
     readonly write: "fs.write";
     readonly exec: "shell.exec";
 };
 /**
  * How `workspaceToolsPlugin` (and `workspaceTools`) works on the workspace,
- * `SessionEnvironment.workspace`. Flat: plugin defaults merge one level deep.
+ * `SessionEnvironment.workspace`. Flat.
  *
  * - `tools`: the tools to register (all seven by default). A skill whose
  *   tools are all left out is left out too.
  * - `always`: the skills active from a turn's first step: `read` by default.
  *   `edit` and `shell` here need their grants (`fs.write`, `shell.exec`), or
  *   the turn fails with `capability.forbidden`; otherwise the model loads
- *   them with `load_skill`, which refuses them without the grants.
+ *   them with `load_skill`, which refuses them without the grants
+ *   (`PermissionDenied`).
  * - `confine`: refuse paths whose real location (links resolved, through the
- *   nearest ancestor that exists) is outside the workspace root.
+ *   nearest ancestor that exists) is outside the workspace and extra roots.
+ * - `workspaceAccess`: `read` refuses writes in the workspace; `write`
+ *   permits them. `roots` adds readable or writable directories, absolute
+ *   or relative to the session's workspace. The longest matching real root
+ *   decides access. These restrictions apply with `confine`; bash remains
+ *   unconfined. An extra root that cannot be resolved is skipped and logged.
  * - `protect`: globs, relative to the root, that `write` and `edit` refuse.
  * - `exclude`: names (or, with a `/`, paths relative to the root) `find`
  *   and `grep` never enter below the directory they search. Both lists are
@@ -34,8 +50,13 @@ export declare const WORKSPACE_PERMISSIONS: {
  *   and the tail of a command's output `bash` keeps.
  * - `lsEntries`, `findResults`, `grepMatches`: the most entries, paths and
  *   matching lines the model gets (a call may ask for fewer).
- * - `grepLineChars`: lines are cut to this many characters before `grep`
- *   matches them, and shown cut.
+ * - `grepLineChars`: the displayed line width; builtin also cuts before matching.
+ * - `grepEngine`: auto probes for rg once over this machine's pair
+ *   (`localSystemPlugin`'s FileSystem and Bash), falling back to builtin,
+ *   and selects builtin over any other pair; ripgrep requires rg over
+ *   whatever pair the host gives. `grepTimeoutMs` bounds rg commands; the synchronous builtin
+ *   engine is not time-bounded. `grepIgnoreFiles` honours ignore files in rg
+ *   only (false searches ignored files too).
  * - `maxFileBytes`: the largest file `read`, `edit` and `grep` load, and
  *   the most of a command's output `bash` saves.
  * - `readImages`: `read` returns a PNG, JPEG, GIF or WebP image (by its
@@ -45,6 +66,9 @@ export declare const WORKSPACE_PERMISSIONS: {
  *   `images`, or memory with `maxMediaChars: 0`) sets `false`: the model
  *   would get a label line in the image's place, and the session would
  *   still store the bytes.
+ * - `imageMaxSide`: with an ImageResizer, fit images to at most this many
+ *   pixels a side (64 to 8000, default 8000). Without a resizer, read keeps
+ *   the existing provider-limit behavior.
  * - `fuzzyEdit`: when an edit's text is not found, match it once more over
  *   whole lines with whitespace, Unicode compatibility forms and smart
  *   quotes normalised (the match must still be unique).
@@ -62,11 +86,18 @@ export declare const WORKSPACE_PERMISSIONS: {
  *   one `tool.progress` event per run of output from one stream.
  * - `environmentSection`, `sectionOrder`: the `workspace.environment`
  *   system-prompt section (tier `session`) and its order.
+ *
+ * @public
  */
 export declare const WorkspaceToolsConfig: Schema.Struct<{
     readonly tools: Schema.$Array<Schema.Literals<readonly ["read", "write", "edit", "ls", "find", "grep", "bash"]>>;
     readonly always: Schema.$Array<Schema.Literals<readonly ["read", "edit", "shell"]>>;
     readonly confine: Schema.Boolean;
+    readonly workspaceAccess: Schema.Literals<readonly ["read", "write"]>;
+    readonly roots: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly access: Schema.Literals<readonly ["read", "write"]>;
+    }>>;
     readonly protect: Schema.$Array<Schema.String>;
     readonly exclude: Schema.$Array<Schema.String>;
     readonly maxLines: Schema.Int;
@@ -75,8 +106,12 @@ export declare const WorkspaceToolsConfig: Schema.Struct<{
     readonly findResults: Schema.Int;
     readonly grepMatches: Schema.Int;
     readonly grepLineChars: Schema.Int;
+    readonly grepEngine: Schema.Literals<readonly ["auto", "ripgrep", "builtin"]>;
+    readonly grepTimeoutMs: Schema.Int;
+    readonly grepIgnoreFiles: Schema.Boolean;
     readonly maxFileBytes: Schema.Int;
     readonly readImages: Schema.Boolean;
+    readonly imageMaxSide: Schema.Int;
     readonly fuzzyEdit: Schema.Boolean;
     readonly bashTimeoutMs: Schema.Int;
     readonly bashMaxTimeoutMs: Schema.Int;
@@ -91,8 +126,13 @@ export declare const WorkspaceToolsConfig: Schema.Struct<{
     readonly sectionOrder: Schema.Int;
 }>;
 export type WorkspaceToolsConfig = typeof WorkspaceToolsConfig.Type;
+/** @public */
 export declare const workspaceToolsDefaults: WorkspaceToolsConfig;
-/** `read`: a file's lines from `offset` (1-based, default 1), at most `limit` of them (and never more than the configured window). */
+/**
+ * `read`: a file's lines from `offset` (1-based, default 1), at most `limit` of them (and never more than the configured window).
+ *
+ * @public
+ */
 export declare const ReadParams: Schema.Struct<{
     readonly path: Schema.String;
     readonly offset: Schema.optionalKey<Schema.Int>;
@@ -112,6 +152,8 @@ export type ReadParams = typeof ReadParams.Type;
  * over `MEDIA_LIMITS.maxPixels` a side, or a header without a size) is an
  * `ImageRejected` note: its type, size and why. Any other binary file is
  * `Binary`, with the media type its name suggests.
+ *
+ * @public
  */
 export declare const ReadResult: Schema.Union<readonly [Schema.TaggedStruct<"Text", {
     readonly path: Schema.String;
@@ -137,6 +179,13 @@ export declare const ReadResult: Schema.Union<readonly [Schema.TaggedStruct<"Tex
         readonly name: Schema.optionalKey<Schema.String>;
         readonly alt: Schema.optionalKey<Schema.String>;
     }>;
+    /** Source dimensions and size when a resizer supplied the returned image; no original image bytes. */
+    readonly original: Schema.optionalKey<Schema.Struct<{
+        readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+        readonly bytes: Schema.Int;
+        readonly width: Schema.Int;
+        readonly height: Schema.Int;
+    }>>;
 }>, Schema.TaggedStruct<"ImageRejected", {
     readonly path: Schema.String;
     readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
@@ -145,24 +194,34 @@ export declare const ReadResult: Schema.Union<readonly [Schema.TaggedStruct<"Tex
     readonly message: Schema.String;
 }>]>;
 export type ReadResult = typeof ReadResult.Type;
+/** @public */
 export declare const WriteParams: Schema.Struct<{
     readonly path: Schema.String;
     readonly content: Schema.String;
 }>;
 export type WriteParams = typeof WriteParams.Type;
-/** What `write` did: how many bytes it wrote, and whether the file is new. */
+/**
+ * What `write` did: how many bytes it wrote, and whether the file is new.
+ *
+ * @public
+ */
 export declare const WriteResult: Schema.Struct<{
     readonly path: Schema.String;
     readonly bytes: Schema.Int;
     readonly created: Schema.Boolean;
 }>;
 export type WriteResult = typeof WriteResult.Type;
-/** One replacement: `oldText` (exactly once in the file) becomes `newText`. */
+/**
+ * One replacement: `oldText` (exactly once in the file) becomes `newText`.
+ *
+ * @public
+ */
 export declare const TextEdit: Schema.Struct<{
     readonly oldText: Schema.String;
     readonly newText: Schema.String;
 }>;
 export type TextEdit = typeof TextEdit.Type;
+/** @public */
 export declare const EditParams: Schema.Struct<{
     readonly path: Schema.String;
     readonly edits: Schema.NonEmptyArray<Schema.Struct<{
@@ -175,6 +234,8 @@ export type EditParams = typeof EditParams.Type;
  * What `edit` did: how many blocks it replaced, whether any was found only
  * after normalising, the first changed line, and the change as a unified
  * diff (for a host's UI; the model is shown a one-line summary).
+ *
+ * @public
  */
 export declare const EditResult: Schema.Struct<{
     readonly path: Schema.String;
@@ -184,17 +245,23 @@ export declare const EditResult: Schema.Struct<{
     readonly diff: Schema.String;
 }>;
 export type EditResult = typeof EditResult.Type;
+/** @public */
 export declare const LsParams: Schema.Struct<{
     readonly path: Schema.optionalKey<Schema.String>;
     readonly limit: Schema.optionalKey<Schema.Int>;
 }>;
 export type LsParams = typeof LsParams.Type;
+/** @public */
 export declare const LsEntry: Schema.Struct<{
     readonly name: Schema.String;
     readonly kind: Schema.Literals<readonly ["file", "directory", "symlink", "other"]>;
 }>;
 export type LsEntry = typeof LsEntry.Type;
-/** A directory's entries by name, at most the limit of them; `total` counts them all. */
+/**
+ * A directory's entries by name, at most the limit of them; `total` counts them all.
+ *
+ * @public
+ */
 export declare const LsResult: Schema.Struct<{
     readonly path: Schema.String;
     readonly entries: Schema.$Array<Schema.Struct<{
@@ -204,13 +271,18 @@ export declare const LsResult: Schema.Struct<{
     readonly total: Schema.Int;
 }>;
 export type LsResult = typeof LsResult.Type;
+/** @public */
 export declare const FindParams: Schema.Struct<{
     readonly pattern: Schema.String;
     readonly path: Schema.optionalKey<Schema.String>;
     readonly limit: Schema.optionalKey<Schema.Int>;
 }>;
 export type FindParams = typeof FindParams.Type;
-/** The files a glob matched, as paths relative to the workspace root; `truncated` when more matched. */
+/**
+ * The files a glob matched, as paths relative to the workspace root; `truncated` when more matched.
+ *
+ * @public
+ */
 export declare const FindResult: Schema.Struct<{
     readonly pattern: Schema.String;
     readonly path: Schema.String;
@@ -218,6 +290,7 @@ export declare const FindResult: Schema.Struct<{
     readonly truncated: Schema.Boolean;
 }>;
 export type FindResult = typeof FindResult.Type;
+/** @public */
 export declare const GrepParams: Schema.Struct<{
     readonly pattern: Schema.String;
     readonly path: Schema.optionalKey<Schema.String>;
@@ -228,7 +301,11 @@ export declare const GrepParams: Schema.Struct<{
     readonly limit: Schema.optionalKey<Schema.Int>;
 }>;
 export type GrepParams = typeof GrepParams.Type;
-/** One line `grep` shows: a matching line, or (`match: false`) a line of context around one. `text` is cut to the configured width. */
+/**
+ * One line `grep` shows: a matching line, or (`match: false`) a line of context around one. `text` is cut to the configured width.
+ *
+ * @public
+ */
 export declare const GrepLine: Schema.Struct<{
     readonly path: Schema.String;
     readonly line: Schema.Int;
@@ -236,11 +313,26 @@ export declare const GrepLine: Schema.Struct<{
     readonly match: Schema.Boolean;
 }>;
 export type GrepLine = typeof GrepLine.Type;
+/**
+ * A file `grep` could not read, and why (`Permission` when access was denied); its view says why in words.
+ *
+ * @public
+ */
+export declare const GrepUnreadable: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly reason: Schema.Literals<readonly ["NotFound", "Exists", "IsDirectory", "NotDirectory", "NotEmpty", "Permission", "Invalid", "Io"]>;
+}>;
+export type GrepUnreadable = typeof GrepUnreadable.Type;
 /**
  * What `grep` found: the matching lines (with their context) in walk order,
  * how many lines matched and in how many files, whether it stopped at the
- * limit, and how many files it skipped (binary, larger than `maxFileBytes`,
- * or resolving outside the workspace).
+ * limit, how many files it skipped (binary, larger than `maxFileBytes`, or
+ * resolving outside the workspace), and the files it could not read
+ * (`unreadable`, empty in results stored before it was recorded). `timedOut`
+ * marks an incomplete ripgrep search (false in older results). Ripgrep counts
+ * only binary skips it reports; files pruned by its walk/size limit are not counted.
+ *
+ * @public
  */
 export declare const GrepResult: Schema.Struct<{
     readonly pattern: Schema.String;
@@ -255,9 +347,18 @@ export declare const GrepResult: Schema.Struct<{
     readonly files: Schema.Int;
     readonly truncated: Schema.Boolean;
     readonly skipped: Schema.Int;
+    readonly unreadable: Schema.withDecodingDefaultKey<Schema.$Array<Schema.Struct<{
+        readonly path: Schema.String;
+        readonly reason: Schema.Literals<readonly ["NotFound", "Exists", "IsDirectory", "NotDirectory", "NotEmpty", "Permission", "Invalid", "Io"]>;
+    }>>, never>;
+    readonly timedOut: Schema.withDecodingDefaultKey<Schema.Boolean, never>;
 }>;
 export type GrepResult = typeof GrepResult.Type;
-/** `bash`: the command, its timeout in seconds, and what to write to its standard input. */
+/**
+ * `bash`: the command, its timeout in seconds, and what to write to its standard input.
+ *
+ * @public
+ */
 export declare const BashParams: Schema.Struct<{
     readonly command: Schema.String;
     readonly timeout: Schema.optionalKey<Schema.Int>;
@@ -271,6 +372,8 @@ export type BashParams = typeof BashParams.Type;
  * workspace root; null when nothing was saved). The file holds at most
  * `maxFileBytes` of the output, its start: `fullOutputCut` when there was
  * more, which was not saved.
+ *
+ * @public
  */
 export declare const BashToolResult: Schema.Struct<{
     readonly command: Schema.String;
@@ -285,7 +388,11 @@ export declare const BashToolResult: Schema.Struct<{
     readonly durationMs: Schema.Number;
 }>;
 export type BashToolResult = typeof BashToolResult.Type;
-/** The tools' names and schemas, for `onTool` subscriptions (a UI showing `edit` diffs, say). */
+/**
+ * The tools' names and schemas, for `onTool` subscriptions (a UI showing `edit` diffs, say).
+ *
+ * @public
+ */
 export declare const workspaceToolSchemas: {
     readonly read: {
         readonly name: "read";
@@ -318,6 +425,13 @@ export declare const workspaceToolSchemas: {
                 readonly name: Schema.optionalKey<Schema.String>;
                 readonly alt: Schema.optionalKey<Schema.String>;
             }>;
+            /** Source dimensions and size when a resizer supplied the returned image; no original image bytes. */
+            readonly original: Schema.optionalKey<Schema.Struct<{
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly bytes: Schema.Int;
+                readonly width: Schema.Int;
+                readonly height: Schema.Int;
+            }>>;
         }>, Schema.TaggedStruct<"ImageRejected", {
             readonly path: Schema.String;
             readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
@@ -408,6 +522,11 @@ export declare const workspaceToolSchemas: {
             readonly files: Schema.Int;
             readonly truncated: Schema.Boolean;
             readonly skipped: Schema.Int;
+            readonly unreadable: Schema.withDecodingDefaultKey<Schema.$Array<Schema.Struct<{
+                readonly path: Schema.String;
+                readonly reason: Schema.Literals<readonly ["NotFound", "Exists", "IsDirectory", "NotDirectory", "NotEmpty", "Permission", "Invalid", "Io"]>;
+            }>>, never>;
+            readonly timedOut: Schema.withDecodingDefaultKey<Schema.Boolean, never>;
         }>;
     };
     readonly bash: {