@xandreed/plugin-workspace 0.14.0 → 0.15.0

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

@@ -1,10 +1,42 @@
-import { Effect, Option } from "effect";
-import type { BashOptions, Media } from "@xandreed/core";
+import { Effect, Option, Schema } from "effect";
+import { ImageResizeError } from "@xandreed/core";
+import type { BashOptions, ImageFitTarget, ImageInput, Media } from "@xandreed/core";
 import type { BashToolResult, EditResult, FindResult, GrepResult, LsResult, ReadResult, WorkspaceSkillName, WorkspaceToolName, WorkspaceToolsConfig, WriteResult } from "./workspace-tools.entity.js";
 /** The skill each tool belongs to, by its short name. */
 export declare const skillOfTool: Readonly<Record<WorkspaceToolName, WorkspaceSkillName>>;
+/**
+ * The parameters `read`, `ls`, `find` and `grep` take under `config`: their
+ * `limit` goes up to the configured cap (`maxLines`, `lsEntries`,
+ * `findResults`, `grepMatches`), so the model is shown the real maximum and
+ * a larger one is refused rather than quietly lowered.
+ */
+export declare const toolParameters: (config: WorkspaceToolsConfig) => {
+    read: Schema.Struct<{
+        readonly limit: Schema.optionalKey<Schema.Int>;
+        readonly path: Schema.String;
+        readonly offset: Schema.optionalKey<Schema.Int>;
+    }>;
+    ls: Schema.Struct<{
+        readonly limit: Schema.optionalKey<Schema.Int>;
+        readonly path: Schema.optionalKey<Schema.String>;
+    }>;
+    find: Schema.Struct<{
+        readonly limit: Schema.optionalKey<Schema.Int>;
+        readonly pattern: Schema.String;
+        readonly path: Schema.optionalKey<Schema.String>;
+    }>;
+    grep: Schema.Struct<{
+        readonly limit: Schema.optionalKey<Schema.Int>;
+        readonly pattern: Schema.String;
+        readonly path: Schema.optionalKey<Schema.String>;
+        readonly glob: Schema.optionalKey<Schema.String>;
+        readonly ignoreCase: Schema.optionalKey<Schema.Boolean>;
+        readonly literal: Schema.optionalKey<Schema.Boolean>;
+        readonly context: Schema.optionalKey<Schema.Int>;
+    }>;
+};
 /** What the model is told each tool does, with the configured limits in it. */
-export declare const toolDescriptions: (config: WorkspaceToolsConfig) => Readonly<Record<WorkspaceToolName, string>>;
+export declare const toolDescriptions: (config: WorkspaceToolsConfig, resizesImages?: boolean) => Readonly<Record<WorkspaceToolName, string>>;
 /** The text of the `workspace.environment` section: where the workspace is and how the enabled tools behave there. */
 export declare const environmentText: (root: string, config: WorkspaceToolsConfig, tools: ReadonlyArray<WorkspaceToolName>) => string;
 /**
@@ -24,9 +56,51 @@ export declare const bashEnvironment: (config: WorkspaceToolsConfig, session: Op
  * by the path; an image it refuses (over `MEDIA_LIMITS.imageBytes`, over
  * `MEDIA_LIMITS.maxPixels` a side, or a header without a size) is an
  * `ImageRejected` note, without the bytes. Anything else is `Binary`, with
- * the media type the name suggests.
+ * `nameType`: the media type the name suggests, as the result carries it
+ * (`null` for none; the adapter reads it with `mediaTypeOf`).
  */
-export declare const binaryRead: (path: string, bytes: Uint8Array, readImages: boolean) => Effect.Effect<ReadResult>;
+type FitImage = (image: ImageInput, target: ImageFitTarget) => Effect.Effect<Uint8Array, ImageResizeError>;
+export declare const binaryRead: (path: string, bytes: Uint8Array<ArrayBufferLike>, readImages: boolean, nameType: string | null, fit?: Option.Option<FitImage> | undefined, maxSide?: number | undefined) => Effect.Effect<{
+    readonly _tag: "Text";
+    readonly path: string;
+    readonly text: string;
+    readonly firstLine: number;
+    readonly lastLine: number;
+    readonly totalLines: number;
+    readonly next: number | null;
+    readonly clipped: boolean;
+    readonly lossy: boolean;
+} | {
+    readonly _tag: "Binary";
+    readonly path: string;
+    readonly bytes: number;
+    readonly mediaType: string | null;
+} | {
+    readonly _tag: "Image";
+    readonly path: string;
+    readonly image: {
+        readonly type: "media";
+        readonly mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+        readonly data: string;
+        readonly fingerprint: string & import("effect/Brand").Brand<"MediaFingerprint">;
+        readonly bytes: number;
+        readonly name?: string;
+        readonly alt?: string;
+    };
+    readonly original?: {
+        readonly mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+        readonly bytes: number;
+        readonly width: number;
+        readonly height: number;
+    };
+} | {
+    readonly _tag: "ImageRejected";
+    readonly path: string;
+    readonly mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+    readonly bytes: number;
+    readonly reason: "Empty" | "InvalidBase64" | "UnsupportedType" | "TooLarge" | "TooManyPixels" | "Unreadable" | "TooMany" | "TooLargeTogether";
+    readonly message: string;
+}, never, never>;
 /**
  * What the model can do about a file over `maxFileBytes`, which `read`
  * refuses unread: with `readImages`, a file named as a PNG, JPEG, GIF or
@@ -49,3 +123,4 @@ export declare const renderGrep: (result: GrepResult, withContext: boolean, maxL
 export declare const compactGrep: (result: GrepResult) => string;
 export declare const renderBash: (result: BashToolResult) => string;
 export declare const compactBash: (result: BashToolResult) => string;
+export {};

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

@@ -1,7 +1,8 @@
-import { Effect, Match, Option, Schema } from "effect";
-import { ImageMediaType, MEDIA_LIMITS, mediaFromBytes, sniffImageType } from "@xandreed/core";
+import { Effect, Match, Option, Result, Schema } from "effect";
+import { fitTarget, imageSizeOf, ImageMediaType, ImageResizeError, MEDIA_LIMITS, mediaFromBytes, sniffImageType } from "@xandreed/core";
 import { renderSearchLines } from "./text-search.entity.functions.js";
 import { formatBytes, headLines, mediaTypeOf } from "./text-window.entity.functions.js";
+import { FindParams, GrepParams, LsParams, ReadParams } from "./workspace-tools.entity.js";
 export const skillOfTool = {
   read: "read",
   ls: "read",
@@ -14,25 +15,36 @@ export const skillOfTool = {
 const seconds = (ms) => `${Math.round(ms / 1000)} s`, imageLimit = (config) => {
   const bytes = Math.min(MEDIA_LIMITS.imageBytes, config.maxFileBytes);
   return bytes < 1048576 ? `${Math.floor(bytes * 100 / 1024) / 100} KB` : `${Math.floor(bytes * 100 / 1048576) / 100} MB`;
-}, listed = (names) => names.length === 0 ? "nothing" : names.join(", ");
-export const toolDescriptions = (config) => ({
-  read: `Read a text file of the workspace${config.readImages ? ", or look at an image" : ""}. Shows at most ${config.maxLines} lines or ${formatBytes(config.maxBytes)} at a time; when more is left, the result says which offset to continue from. offset is the first line to show (1-based), limit how many lines. ${config.readImages ? `A PNG, JPEG, GIF or WebP image (up to ${imageLimit(config)} and ${MEDIA_LIMITS.maxPixels} pixels a side) is returned as an image you can see; another binary file is reported, not shown.` : "A binary file is reported, not shown."} To see a directory, use ls.`,
+}, inWords = (names, joiner) => names.length <= 1 ? names.join("") : `${names.slice(0, -1).join(", ")} ${joiner} ${names.at(-1)}`, counted = (n, one, many) => `${n} ${n === 1 ? one : many}`, place = (path) => path === "." ? "the workspace root" : path, limitUpTo = (maximum) => Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum })));
+export const toolParameters = (config) => ({
+  read: Schema.Struct({ ...ReadParams.fields, limit: limitUpTo(config.maxLines) }),
+  ls: Schema.Struct({ ...LsParams.fields, limit: limitUpTo(config.lsEntries) }),
+  find: Schema.Struct({ ...FindParams.fields, limit: limitUpTo(config.findResults) }),
+  grep: Schema.Struct({ ...GrepParams.fields, limit: limitUpTo(config.grepMatches) })
+}), toolDescriptions = (config, resizesImages = !1) => ({
+  read: `Read a text file of the workspace${config.readImages ? ", or look at an image" : ""}. Shows at most ${config.maxLines} lines or ${formatBytes(config.maxBytes)} at a time; when more is left, the result says which offset to continue from. offset is the first line to show (1-based), limit how many lines (at most ${config.maxLines}). ${config.readImages ? resizesImages ? `A PNG, JPEG, GIF or WebP image is returned as an image you can see; larger images are scaled down to fit ${config.imageMaxSide} pixels a side and ${MEDIA_LIMITS.imageBytes / 1048576} MB. Files over ${formatBytes(config.maxFileBytes)} are refused before resizing. Another binary file is reported, not shown.` : `A PNG, JPEG, GIF or WebP image (up to ${imageLimit(config)} and ${MEDIA_LIMITS.maxPixels} pixels a side) is returned as an image you can see; another binary file is reported, not shown.` : "A binary file is reported, not shown."} To see a directory, use ls.`,
   write: "Create a file, or replace all of an existing one, with content; missing directories are created. To change part of a file, use edit. Emptying a non-empty file is refused.",
   edit: "Change part of a file by replacing exact text. Each edit's oldText must appear exactly once in the file: copy it from read (without the notice lines), with enough surrounding lines to be unique. All edits are matched against the file as it was before this call and must not overlap; newText replaces oldText (empty to delete it). Line endings and a byte-order mark are kept.",
-  ls: `List a directory (by default the workspace root): one entry per line, directories ending in /, symbolic links in @. At most ${config.lsEntries} entries.`,
-  find: `Find files whose path matches a glob pattern, relative to path (by default the workspace root): * and ? match within a name, ** any number of directories, {a,b} either; e.g. **/*.ts or src/**/test_*.py. Never looks inside ${listed(config.exclude)} or symbolic links. At most ${config.findResults} paths.`,
-  grep: `Search file contents for a regular expression (JavaScript syntax), or for plain text with literal: true. path is a file or a directory (by default the workspace root); glob limits the files searched (*.ts searches every directory). Shows path:line:text for each matching line, and context lines around each match when asked. Lines are cut to ${config.grepLineChars} characters before matching. At most ${config.grepMatches} matching lines; binary files, ${listed(config.exclude)} and symbolic links are skipped.`,
+  ls: `List a directory (by default the workspace root): one entry per line, directories ending in /, symbolic links in @. At most ${config.lsEntries} entries; limit (1 to ${config.lsEntries}) asks for fewer.`,
+  find: `Find files whose path matches a glob pattern, relative to path (by default the workspace root): * and ? match within a name, ** any number of directories, {a,b} either; e.g. **/*.ts or src/**/test_*.py. Never looks inside ${inWords([...config.exclude, "symbolic links"], "or")}. At most ${config.findResults} paths; limit (1 to ${config.findResults}) asks for fewer.`,
+  grep: `Search file contents for a regular expression (${config.grepEngine === "ripgrep" ? "ripgrep syntax: no lookaround or backreferences" : "JavaScript syntax"}), or for plain text with literal: true. path is a file or a directory (by default the workspace root); glob limits the files searched (*.ts searches every directory). Shows path:line:text for each matching line, and context lines around each match when asked. ${config.grepEngine === "ripgrep" ? `Lines longer than ${config.grepLineChars} characters are shown cut. The search stops after ${seconds(config.grepTimeoutMs)}.` : `Lines are cut to ${config.grepLineChars} characters before matching.`} At most ${config.grepMatches} matching lines; limit (1 to ${config.grepMatches}) asks for fewer. ${inWords(["Binary files", ...config.exclude, "symbolic links"], "and")} are skipped, and files that cannot be read are named.`,
   bash: `Run a shell command with bash -c in the workspace root. timeout is in seconds (default ${seconds(config.bashTimeoutMs)}, at most ${seconds(config.bashMaxTimeoutMs)}); stdin is written to the command's standard input. Returns the exit code and the output, stdout and stderr in the order they came. Output longer than ${config.maxLines} lines or ${formatBytes(config.maxBytes)} is cut to its end${config.spillDir === null ? "" : `, and the whole of it (up to ${formatBytes(config.maxFileBytes)}) is saved to a file you can read`}. A non-zero exit code is a result to read, not a failure. Anything the command leaves running may be stopped when it returns.`
 }), environmentText = (root, config, tools) => {
-  const has = (tool) => tools.includes(tool);
+  const has = (tool) => tools.includes(tool), fileTools = tools.some((tool) => tool !== "bash"), extra = (access) => config.roots.filter((root) => root.access === access).map((root) => root.path), readable = extra("read"), writable = extra("write"), rootAccess = [
+    ...readable.length > 0 ? [`read ${inWords(readable, "and")}`] : [],
+    ...writable.length > 0 ? [`read and change ${inWords(writable, "and")}`] : []
+  ];
   return [
     "## Workspace",
-    `The workspace is ${root}. Give paths relative to it${config.confine ? "; the tools refuse paths that lead outside it." : "."}`,
+    `The workspace is ${root}. Give paths relative to it${config.confine && fileTools ? config.roots.length === 0 ? "; the file tools refuse paths that lead outside it." : "; the file tools refuse paths that lead outside it and the allowed roots." : "."}`,
+    ...config.confine && fileTools && rootAccess.length > 0 ? [`${rootAccess.map((access) => `The file tools may also ${access}.`).join(" ")} Extra roots are relative to the workspace unless absolute.`] : [],
+    ...config.confine && config.workspaceAccess === "read" && (has("write") || has("edit")) ? ["write and edit change nothing in the workspace unless a writable extra root permits it."] : [],
     ...has("read") ? [`read shows a file ${config.maxLines} lines or ${formatBytes(config.maxBytes)} at a time; continue with the offset it gives.`] : [],
-    ...has("find") || has("grep") ? [`find and grep never look inside ${listed(config.exclude)}.`] : [],
+    ...(has("find") || has("grep")) && config.exclude.length > 0 ? [`find and grep never look inside ${config.exclude.join(", ")}.`] : [],
+    ...has("grep") && config.grepEngine === "ripgrep" && config.grepIgnoreFiles ? ["grep honours .gitignore, .ignore and other ripgrep ignore files."] : [],
     ...has("edit") ? ["edit replaces exact text: read the file first and copy the text to change from it."] : [],
-    ...has("write") || has("edit") ? [config.protect.length === 0 ? "" : `write and edit leave ${listed(config.protect)} alone.`] : [],
-    ...has("bash") ? [`bash runs commands in the workspace root with a ${seconds(config.bashTimeoutMs)} timeout.${config.spillDir === null ? "" : " When their output is cut, the whole of it is saved to a file under " + config.spillDir + " that read can open."}`] : []
+    ...has("write") || has("edit") ? [config.protect.length === 0 ? "" : `write and edit leave ${config.protect.join(", ")} alone in the workspace.`] : [],
+    ...has("bash") ? [`bash runs commands in the workspace root with a ${seconds(config.bashTimeoutMs)} timeout.${config.spillDir === null ? "" : " When their output is cut, the whole of it is saved to a file under " + config.spillDir + " that read can open."} Shell commands are not confined by the file tools' roots or read-only access.`] : []
   ].filter((line) => line.length > 0).join(`
 `);
 }, bashEnvironment = (config, session) => ({
@@ -44,12 +56,25 @@ export const toolDescriptions = (config) => ({
     ...config.bashEnv
   },
   inheritEnv: config.bashInheritEnv ? !0 : config.bashEnvAllow
-}), binaryRead = (path, bytes, readImages) => Option.match(readImages ? sniffImageType(bytes) : Option.none(), {
-  onNone: () => Effect.succeed({ _tag: "Binary", path, bytes: bytes.length, mediaType: Option.getOrNull(mediaTypeOf(path)) }),
-  onSome: (mediaType) => mediaFromBytes(bytes, { name: path }).pipe(Effect.match({
+}), binaryRead = Effect.fnUntraced(function* (path, bytes, readImages, nameType, fit = Option.none(), maxSide = MEDIA_LIMITS.maxPixels) {
+  const type = readImages ? sniffImageType(bytes) : Option.none();
+  if (Option.isNone(type))
+    return { _tag: "Binary", path, bytes: bytes.length, mediaType: nameType };
+  const mediaType = type.value, initial = yield* Effect.result(mediaFromBytes(bytes, { name: path })), size = imageSizeOf(bytes, mediaType), ordinary = Result.match(initial, {
     onSuccess: (image) => ({ _tag: "Image", path, image }),
     onFailure: (rejected) => ({ _tag: "ImageRejected", path, mediaType, bytes: bytes.length, reason: rejected.reason, message: rejected.message })
-  }))
+  });
+  if (Option.isNone(fit) || Option.isNone(size) || Result.isSuccess(initial) && Math.max(size.value.width, size.value.height) <= maxSide)
+    return ordinary;
+  const source = size.value, target = fitTarget(maxSide), fitted = yield* Effect.result(fit.value({ bytes, mediaType }, target).pipe(Effect.flatMap((output) => mediaFromBytes(output, { name: path }).pipe(Effect.flatMap((image) => {
+    const actual = imageSizeOf(output, image.mediaType);
+    return Option.isSome(actual) && Math.max(actual.value.width, actual.value.height) <= target.maxSide ? Effect.succeed(image) : Effect.fail(new ImageResizeError({ reason: "Failed", message: "the fitted image exceeds the requested pixel limit" }));
+  })))));
+  if (Result.isFailure(fitted)) {
+    yield* Effect.logWarning("read: the image could not be fitted", fitted.failure);
+    return Result.isFailure(initial) ? ordinary : { _tag: "ImageRejected", path, mediaType, bytes: bytes.length, reason: "TooManyPixels", message: `the image is ${source.width}x${source.height} pixels, more than ${maxSide} a side` };
+  }
+  return { _tag: "Image", path, image: fitted.success, original: { mediaType, bytes: bytes.length, width: source.width, height: source.height } };
 }), fileTooLargeHint = (path, readImages) => readImages && Option.exists(mediaTypeOf(path), Schema.is(ImageMediaType)) ? "to see it, make a smaller copy with bash (scaled down or recompressed) and read that" : "use grep to find lines in it, or bash (head, tail, sed -n) for parts of it", readMedia = (result) => Match.valueTags(result, {
   Text: () => [],
   Binary: () => [],
@@ -68,7 +93,7 @@ const rejectedHint = {
 };
 export const renderRead = (result) => Match.valueTags(result, {
   Binary: (binary) => `[${binary.path} is a binary file (${formatBytes(binary.bytes)}${binary.mediaType === null ? "" : `, ${binary.mediaType}`}); it cannot be shown as text.]`,
-  Image: (read) => `[Image ${read.path} (${read.image.mediaType}, ${formatBytes(read.image.bytes)}).]`,
+  Image: (read) => `[Image ${read.path} (${read.image.mediaType}, ${formatBytes(read.image.bytes)})${read.original === void 0 ? "" : `, scaled down from ${read.original.width}x${read.original.height} (${read.original.mediaType}, ${formatBytes(read.original.bytes)})`}.]`,
   ImageRejected: (read) => `[${read.path} is an image (${read.mediaType}, ${formatBytes(read.bytes)}) that read cannot show: ${read.message}.${rejectedHint[read.reason]}]`,
   Text: (text) => text.totalLines === 0 ? `[${text.path} is empty.]` : [
     text.text,
@@ -77,10 +102,21 @@ export const renderRead = (result) => Match.valueTags(result, {
     ...text.next === null ? [] : [`[Showing lines ${text.firstLine}-${text.lastLine} of ${text.totalLines}. Use offset=${text.next} to continue.]`]
   ].join(`
 `)
-}), compactRead = (result) => Match.valueTags(result, {
+});
+const rejectedWhy = {
+  TooLarge: "too large to send",
+  TooManyPixels: "more pixels a side than the limit",
+  Unreadable: "its header gives no size",
+  Empty: "it has no bytes",
+  InvalidBase64: "its data is not base64",
+  UnsupportedType: "not a PNG, JPEG, GIF or WebP image",
+  TooMany: "too many images at once",
+  TooLargeTogether: "too large together with the other images"
+};
+export const compactRead = (result) => Match.valueTags(result, {
   Binary: (binary) => `(read ${binary.path}: binary, ${formatBytes(binary.bytes)})`,
-  Image: (read) => `(read ${read.path}: ${read.image.mediaType} image, ${formatBytes(read.image.bytes)})`,
-  ImageRejected: (read) => `(read ${read.path}: ${read.mediaType} image not shown, ${read.reason})`,
+  Image: (read) => `(read ${read.path}: ${read.image.mediaType} image, ${formatBytes(read.image.bytes)}${read.original === void 0 ? "" : `, scaled down from ${read.original.width}x${read.original.height} (${read.original.mediaType}, ${formatBytes(read.original.bytes)})`})`,
+  ImageRejected: (read) => `(read ${read.path}: ${read.mediaType} image not shown, ${rejectedWhy[read.reason]})`,
   Text: (text) => `(read ${text.path}: lines ${text.firstLine}-${text.lastLine} of ${text.totalLines})`
 }), renderWrite = (result) => `${result.created ? "Created" : "Replaced"} ${result.path} (${formatBytes(result.bytes)}).`, compactWrite = (result) => `(${result.created ? "created" : "replaced"} ${result.path}: ${formatBytes(result.bytes)})`, renderEdit = (result) => `Replaced ${result.replaced} block${result.replaced === 1 ? "" : "s"} in ${result.path}; the first change is at line ${result.firstChangedLine}.${result.normalized ? " Some text matched only once whitespace and quotes were normalised: read the changed lines to check them." : ""}`, compactEdit = (result) => `(edited ${result.path}: ${result.replaced} block${result.replaced === 1 ? "" : "s"} from line ${result.firstChangedLine})`;
 const lsSuffix = { file: "", directory: "/", symlink: "@", other: "" };
@@ -88,29 +124,47 @@ export const renderLs = (result) => result.total === 0 ? `[${result.path} is emp
   ...result.entries.map((entry) => `${entry.name}${lsSuffix[entry.kind]}`),
   ...result.entries.length < result.total ? [`[Showing ${result.entries.length} of ${result.total} entries. Use find with a pattern to narrow them down.]`] : []
 ].join(`
-`), compactLs = (result) => `(listed ${result.path}: ${result.total} entries)`, renderFind = (result, maxLines, maxBytes) => {
+`), compactLs = (result) => `(listed ${result.path}: ${counted(result.total, "entry", "entries")})`, renderFind = (result, maxLines, maxBytes) => {
   if (result.paths.length === 0)
-    return `No files under ${result.path} match ${result.pattern}.`;
+    return `No files under ${place(result.path)} match ${result.pattern}.`;
   const head = headLines(result.paths, maxLines, maxBytes);
   return [
     ...head.lines,
-    ...head.omitted > 0 ? [`[${head.omitted} more paths not shown. Narrow the pattern or the path.]`] : result.truncated ? [`[Stopped at ${result.paths.length} paths; there are more. Narrow the pattern or the path.]`] : []
+    ...head.omitted > 0 ? [`[${counted(head.omitted, "more path", "more paths")} not shown. Narrow the pattern or the path.]`] : result.truncated ? [`[Stopped at ${counted(result.paths.length, "path", "paths")}; there are more. Narrow the pattern or the path.]`] : []
   ].join(`
 `);
-}, compactFind = (result) => `(find ${result.pattern} in ${result.path}: ${result.paths.length}${result.truncated ? "+" : ""} paths)`, renderGrep = (result, withContext, maxLines, maxBytes) => {
-  const skipped = result.skipped === 0 ? [] : [`[${result.skipped} file${result.skipped === 1 ? "" : "s"} skipped: binary, larger than the read limit, or leading outside the workspace.]`];
+}, compactFind = (result) => `(find ${result.pattern} in ${result.path}: ${result.truncated ? `${result.paths.length}+ paths` : counted(result.paths.length, "path", "paths")})`;
+const unreadableWhy = {
+  NotFound: "no longer there",
+  NotDirectory: "no longer there",
+  Permission: "permission denied",
+  Invalid: "not a path the file system accepts",
+  Exists: "a file-system error",
+  IsDirectory: "a file-system error",
+  NotEmpty: "a file-system error",
+  Io: "a file-system error"
+}, unreadableLines = (result) => Array.from(new Set(result.unreadable.map((file) => unreadableWhy[file.reason])), (why) => {
+  const paths = result.unreadable.filter((file) => unreadableWhy[file.reason] === why).map((file) => file.path);
+  return `[Could not read ${paths.length} file${paths.length === 1 ? "" : "s"}, ${why}: ${paths.slice(0, 5).join(", ")}${paths.length > 5 ? `, and ${paths.length - 5} more` : ""}.]`;
+});
+export const renderGrep = (result, withContext, maxLines, maxBytes) => {
+  const skipped = [
+    ...result.timedOut ? ["[Search timed out; these are partial results. Narrow the pattern or the path and search again.]"] : [],
+    ...result.skipped === 0 ? [] : [`[${result.skipped} file${result.skipped === 1 ? "" : "s"} skipped: binary, larger than the read limit, or leading outside the workspace.]`],
+    ...unreadableLines(result)
+  ];
   if (result.matches === 0)
-    return [`No matches for ${result.pattern} in ${result.path}.`, ...skipped].join(`
+    return [`No matches for ${result.pattern} in ${place(result.path)}.`, ...skipped].join(`
 `);
   const head = headLines(renderSearchLines(result.lines, withContext), maxLines, maxBytes);
   return [
     ...head.lines,
-    ...head.omitted > 0 ? [`[${head.omitted} more lines not shown. Narrow the pattern or the path.]`] : [],
-    ...result.truncated ? [`[Stopped at ${result.matches} matching lines; there are more. Narrow the pattern or the path, or raise limit.]`] : [],
+    ...head.omitted > 0 ? [`[${counted(head.omitted, "more line", "more lines")} not shown. Narrow the pattern or the path.]`] : [],
+    ...result.truncated ? [`[Stopped at ${counted(result.matches, "matching line", "matching lines")}; there are more. Narrow the pattern or the path, or raise limit.]`] : [],
     ...skipped
   ].join(`
 `);
-}, compactGrep = (result) => `(grep ${result.pattern} in ${result.path}: ${result.matches}${result.truncated ? "+" : ""} matching lines in ${result.files} files)`;
+}, compactGrep = (result) => `(grep ${result.pattern} in ${result.path}: ${result.truncated ? `${result.matches}+ matching lines` : counted(result.matches, "matching line", "matching lines")} in ${counted(result.files, "file", "files")}${result.timedOut ? "; timed out, partial results" : ""})`;
 const endOf = (result) => result.termination === "timeout" ? `[The command was killed after ${result.durationMs < 1e4 ? `${(result.durationMs / 1000).toFixed(1)} s` : seconds(result.durationMs)}, at its timeout.]` : result.termination === "interrupted" ? "[The command was stopped before it finished.]" : result.termination === "signal" ? `[The command was killed by ${result.signal ?? "a signal"}.]` : `[Exit code ${result.exitCode ?? "unknown"}.]`, cutOf = (result) => {
   const shownLines = result.output.length === 0 ? 0 : result.output.split(`
 `).length, what = shownLines < result.totalLines ? `Output cut to its last ${shownLines} of ${result.totalLines} lines.` : "Output cut: only the end of its last line is shown.", saved = result.fullOutput === null ? "" : result.fullOutputCut ? ` Only its start was saved, in ${result.fullOutput}: the output grew past the size read opens, and the rest was not kept. Read the file with offset to see that start; to see the rest, run the command again with its output filtered (grep, tail, sed -n).` : ` The whole output is in ${result.fullOutput}; read it with offset to see the rest.`;
@@ -121,4 +175,6 @@ export const renderBash = (result) => [
   ...result.truncated ? [cutOf(result)] : [],
   endOf(result)
 ].join(`
-`), compactBash = (result) => `(ran ${result.command.length > 80 ? `${result.command.slice(0, 80)}\u2026` : result.command}: ${result.termination === "exit" ? `exit ${result.exitCode ?? "?"}` : result.termination}${result.fullOutput === null ? "" : `; output in ${result.fullOutput}`})`;
+`);
+const endedIn = (result) => Match.value(result.termination).pipe(Match.when("exit", () => `exit ${result.exitCode ?? "?"}`), Match.when("timeout", () => "killed at its timeout"), Match.when("signal", () => `killed by ${result.signal ?? "a signal"}`), Match.when("interrupted", () => "stopped before it finished"), Match.exhaustive);
+export const compactBash = (result) => `(ran ${result.command.length > 80 ? `${result.command.slice(0, 80)}\u2026` : result.command}: ${endedIn(result)}${result.fullOutput === null ? "" : `; output in ${result.fullOutput}`})`;

package/dist/workspace-tools.entity.js

@@ -1,11 +1,14 @@
-import { Result, Schema } from "effect";
-import { AttachmentRejectedReason, BASH_ENV_ALLOWLIST, BashTermination, compileGlob, ImageMediaType, Media } from "@xandreed/core";
+import { Effect, Result, Schema } from "effect";
+import { AttachmentRejectedReason, BASH_ENV_ALLOWLIST, MEDIA_LIMITS, BashTermination, compileGlob, FsReason, ImageMediaType, Media } from "@xandreed/core";
+import { WorkspaceAccessMode, WorkspaceAllowedRoot } from "./workspace-path.entity.js";
 export const WorkspaceToolName = Schema.Literals(["read", "write", "edit", "ls", "find", "grep", "bash"]), WorkspaceSkillName = Schema.Literals(["read", "edit", "shell"]), WORKSPACE_PERMISSIONS = { write: "fs.write", exec: "shell.exec" };
 const atLeast = (minimum) => Schema.Int.check(Schema.isGreaterThanOrEqualTo(minimum)), between = (minimum, maximum) => Schema.Int.check(Schema.isBetween({ minimum, maximum })), InsideWorkspace = Schema.String.check(Schema.makeFilter((path) => path.length > 0 && !path.startsWith("/") && !path.split("/").includes("..") ? !0 : "a path relative to the workspace root, without a .. segment")), Glob = Schema.String.check(Schema.makeFilter((glob) => Result.match(compileGlob(glob, { dot: !0 }), { onSuccess: () => !0, onFailure: (reason) => `not a usable glob: ${reason}` })));
 export const WorkspaceToolsConfig = Schema.Struct({
   tools: Schema.Array(WorkspaceToolName),
   always: Schema.Array(WorkspaceSkillName),
   confine: Schema.Boolean,
+  workspaceAccess: WorkspaceAccessMode,
+  roots: Schema.Array(WorkspaceAllowedRoot),
   protect: Schema.Array(Glob),
   exclude: Schema.Array(Glob),
   maxLines: between(1, 1e5),
@@ -14,8 +17,12 @@ export const WorkspaceToolsConfig = Schema.Struct({
   findResults: between(1, 1e5),
   grepMatches: between(1, 1e4),
   grepLineChars: between(16, 1e5),
+  grepEngine: Schema.Literals(["auto", "ripgrep", "builtin"]),
+  grepTimeoutMs: atLeast(1),
+  grepIgnoreFiles: Schema.Boolean,
   maxFileBytes: between(1024, 1073741824),
   readImages: Schema.Boolean,
+  imageMaxSide: between(64, MEDIA_LIMITS.maxPixels),
   fuzzyEdit: Schema.Boolean,
   bashTimeoutMs: atLeast(1),
   bashMaxTimeoutMs: atLeast(1),
@@ -32,6 +39,8 @@ export const WorkspaceToolsConfig = Schema.Struct({
   tools: ["read", "write", "edit", "ls", "find", "grep", "bash"],
   always: ["read"],
   confine: !0,
+  workspaceAccess: "write",
+  roots: [],
   protect: [".git/**", ".efferent/**"],
   exclude: ["node_modules", ".git", ".efferent"],
   maxLines: 2000,
@@ -40,8 +49,12 @@ export const WorkspaceToolsConfig = Schema.Struct({
   findResults: 1000,
   grepMatches: 100,
   grepLineChars: 500,
+  grepEngine: "auto",
+  grepTimeoutMs: 30000,
+  grepIgnoreFiles: !1,
   maxFileBytes: 33554432,
   readImages: !0,
+  imageMaxSide: MEDIA_LIMITS.maxPixels,
   fuzzyEdit: !0,
   bashTimeoutMs: 120000,
   bashMaxTimeoutMs: 600000,
@@ -76,7 +89,13 @@ export const WorkspaceToolsConfig = Schema.Struct({
   }),
   Schema.TaggedStruct("Image", {
     path: Schema.String,
-    image: Media
+    image: Media,
+    original: Schema.optionalKey(Schema.Struct({
+      mediaType: ImageMediaType,
+      bytes: atLeast(1),
+      width: atLeast(1),
+      height: atLeast(1)
+    }))
   }),
   Schema.TaggedStruct("ImageRejected", {
     path: Schema.String,
@@ -99,14 +118,16 @@ export const WorkspaceToolsConfig = Schema.Struct({
   literal: Schema.optionalKey(Schema.Boolean),
   context: Schema.optionalKey(between(0, 10)),
   limit: Schema.optionalKey(atLeast(1))
-}), GrepLine = Schema.Struct({ path: Schema.String, line: Schema.Int, text: Schema.String, match: Schema.Boolean }), GrepResult = Schema.Struct({
+}), GrepLine = Schema.Struct({ path: Schema.String, line: Schema.Int, text: Schema.String, match: Schema.Boolean }), GrepUnreadable = Schema.Struct({ path: Schema.String, reason: FsReason }), GrepResult = Schema.Struct({
   pattern: Schema.String,
   path: Schema.String,
   lines: Schema.Array(GrepLine),
   matches: Schema.Int,
   files: Schema.Int,
   truncated: Schema.Boolean,
-  skipped: Schema.Int
+  skipped: Schema.Int,
+  unreadable: Schema.Array(GrepUnreadable).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+  timedOut: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(!1)))
 }), BashParams = Schema.Struct({
   command: Schema.String,
   timeout: Schema.optionalKey(atLeast(1)),

package/dist/write-tools.adapter.js

@@ -6,10 +6,10 @@ import { decodeText, encodeText, formatBytes, looksBinary, utf8Length } from "./
 import { checkWritable, fsFailure, openWorkspace, resolveTarget } from "./workspace-path.entity.functions.js";
 import { EditParams, EditResult, WORKSPACE_PERMISSIONS, WriteParams, WriteResult } from "./workspace-tools.entity.js";
 import { compactEdit, compactWrite, renderEdit, renderWrite, toolDescriptions } from "./workspace-tools.entity.functions.js";
-import { failure, fileSubjects, notAFile } from "./read-tools.adapter.js";
+import { failure, fileSubjects, notAFile, WORKSPACE_SERVICES } from "./read-tools.adapter.js";
 const WriteTool = (description) => Tool.make("write", { description, parameters: WriteParams, success: WriteResult, failure: Failure, failureMode: "return" }), EditTool = (description) => Tool.make("edit", { description, parameters: EditParams, success: EditResult, failure: Failure, failureMode: "return" }), holding = (context, path) => (change) => Effect.scoped(RcMap.get(context.locks, path).pipe(Effect.flatMap((lock) => lock.withPermits(1)(change)))), existing = (access, target) => access.fs.stat(target.path).pipe(Effect.map(Option.some), Effect.catchIf((error) => error.reason === "NotFound", () => Effect.succeed(Option.none())), Effect.mapError(fsFailure(target.display))), notForNewFiles = 3657, save = (access, target, content, before) => {
   const mode = Option.flatMap(before, (info) => info.mode), inPlace = access.fs.write(target.path, content), replaced = Effect.gen(function* () {
-    const suffix = (yield* Random.nextIntBetween(0, 2147483647)).toString(36), temporary = access.path.join(access.path.dirname(target.path), `.${access.path.basename(target.path)}.${suffix}.efferent-tmp`), discard = access.fs.remove(temporary).pipe(Effect.ignore);
+    const suffix = (yield* Random.nextIntBetween(0, 2147483647)).toString(36), temporary = access.path.join(access.path.dirname(target.path), `.${access.path.basename(target.path)}.${suffix}.efferent-tmp`), discard = access.fs.remove(temporary).pipe(Effect.ignore({ log: "Warn", message: `the temporary file ${temporary} was not removed` }));
     yield* access.fs.write(temporary, content, { createParents: !0 });
     if (!(yield* Option.match(mode, {
       onNone: () => Effect.succeed(!0),
@@ -22,13 +22,14 @@ const WriteTool = (description) => Tool.make("write", { description, parameters:
 };
 export const writeTool = (context) => defineTool({
   tool: WriteTool(toolDescriptions(context.config).write),
+  requires: WORKSPACE_SERVICES,
   handler: (params) => Effect.gen(function* () {
-    const access = yield* openWorkspace(context.path), target = yield* resolveTarget(access, params.path, { confine: context.config.confine });
+    const access = yield* openWorkspace(context.path, context.config), target = yield* resolveTarget(access, params.path, { confine: context.config.confine, intent: "write" });
     yield* checkWritable(access, target, context.protect);
     return yield* holding(context, target.path)(Effect.gen(function* () {
       const before = yield* existing(access, target);
       if (Option.exists(before, (info) => info.kind === "directory"))
-        return yield* Effect.fail(failure("IsDirectory", `${target.display} is a directory`));
+        return yield* Effect.fail(failure("IsDirectory", `${target.display} is a directory; write takes the path of a file`));
       if (Option.exists(before, (info) => info.kind !== "file"))
         return yield* Effect.fail(notAFile(target.display, "write"));
       if (params.content.length === 0 && Option.exists(before, (info) => info.size > 0))
@@ -41,8 +42,9 @@ export const writeTool = (context) => defineTool({
   annotations: { permissions: [WORKSPACE_PERMISSIONS.write] }
 }), editTool = (context) => defineTool({
   tool: EditTool(toolDescriptions(context.config).edit),
+  requires: WORKSPACE_SERVICES,
   handler: (params) => Effect.gen(function* () {
-    const { config } = context, access = yield* openWorkspace(context.path), target = yield* resolveTarget(access, params.path, { confine: config.confine });
+    const { config } = context, access = yield* openWorkspace(context.path, context.config), target = yield* resolveTarget(access, params.path, { confine: config.confine, intent: "write" });
     yield* checkWritable(access, target, context.protect);
     return yield* holding(context, target.path)(Effect.gen(function* () {
       const before = yield* existing(access, target), info = yield* Option.match(before, {
@@ -50,14 +52,14 @@ export const writeTool = (context) => defineTool({
         onSome: Effect.succeed
       });
       if (info.kind === "directory")
-        return yield* Effect.fail(failure("IsDirectory", `${target.display} is a directory`));
+        return yield* Effect.fail(failure("IsDirectory", `${target.display} is a directory; edit takes the path of a file`));
       if (info.kind !== "file")
         return yield* Effect.fail(notAFile(target.display, "edit"));
       if (info.size > config.maxFileBytes)
-        return yield* Effect.fail(failure("FileTooLarge", `${target.display} is ${formatBytes(info.size)}, more than the ${formatBytes(config.maxFileBytes)} edit loads`));
+        return yield* Effect.fail(failure("FileTooLarge", `${target.display} is ${formatBytes(info.size)}, more than the ${formatBytes(config.maxFileBytes)} edit loads; change it with bash (sed -i, or a script)`));
       const bytes = yield* access.fs.readBytes(target.path).pipe(Effect.mapError(fsFailure(target.display)));
       if (looksBinary(bytes))
-        return yield* Effect.fail(failure("Binary", `${target.display} is a binary file; edit changes text files only`));
+        return yield* Effect.fail(failure("BinaryFile", `${target.display} is a binary file; edit changes text files only`));
       const decoded = decodeText(bytes);
       if (decoded.lossy)
         return yield* Effect.fail(failure("NotUtf8", `${target.display} is not valid UTF-8 (Latin-1 or another encoding, say); edit changes UTF-8 text files only, since it would replace the bytes it cannot decode. Use bash (sed, iconv) to change it`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xandreed/plugin-workspace",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "engines": {
     "node": ">=24",
     "bun": ">=1.3.0"
@@ -14,12 +14,13 @@
       "default": "./dist/index.js"
     }
   },
-  "dependencies": {
-    "@xandreed/core": "0.14.0",
-    "effect": "4.0.7"
-  },
+  "dependencies": {},
   "private": false,
   "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "@xandreed/core": "^0.15.0",
+    "effect": "^4.0.7"
+  },
   "files": [
     "dist",
     "skills",

package/dist/bash.adapter.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/file-system.adapter.test.d.ts

@@ -1 +0,0 @@
-export {};

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

@@ -1 +0,0 @@
-export {};

package/dist/plugin.adapter.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/skills/skills-directory.adapter.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/skills/skills-directory.entity.functions.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/text-edit.entity.functions.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/text-search.entity.functions.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/text-window.entity.functions.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/workspace-path.entity.functions.test.d.ts

@@ -1 +0,0 @@
-export {};

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

@@ -1 +0,0 @@
-export {};

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

@@ -1 +0,0 @@
-export {};

package/dist/workspace-tools.journey.test.d.ts

@@ -1 +0,0 @@
-export {};