@xandreed/plugin-workspace 0.14.0 → 0.15.1

package/README.md

@@ -1,5 +1,5 @@
 # @xandreed/plugin-workspace
 
-Efferent composable agent framework, 0.14.0. Node 24 or Bun.
+Efferent composable agent framework, 0.15.1. Node 24 or Bun.
 
 Documentation: https://github.com/xandreeddev/efferent

package/dist/bash-tool.adapter.js

@@ -1,21 +1,22 @@
 import { Tool } from "effect/ai";
-import { Clock, Effect, Option, Random, Stream } from "effect";
-import { Bash, CurrentToolInvocation, defineTool, Failure, publishToolProgress, RunContext } from "@xandreed/core";
+import { Array as Arr, Clock, Effect, Option, Order, Random, Stream } from "effect";
+import { Bash, BashEvent, CurrentToolInvocation, defineTool, Failure, publishToolProgress, RunContext } from "@xandreed/core";
 import { clipHead, tailText, utf8Length } from "./text-window.entity.functions.js";
 import { openWorkspace } from "./workspace-path.entity.functions.js";
 import { BashParams, BashToolResult, WORKSPACE_PERMISSIONS } from "./workspace-tools.entity.js";
 import { bashEnvironment, compactBash, renderBash, toolDescriptions } from "./workspace-tools.entity.functions.js";
-import { failure } from "./read-tools.adapter.js";
-const BashTool = (description) => Tool.make("bash", { description, parameters: BashParams, success: BashToolResult, failure: Failure, failureMode: "return" }), isChunk = (event) => event._tag === "BashChunk", isExit = (event) => event._tag === "BashExit", runsOf = (chunks) => chunks.reduce((runs, chunk) => {
+import { failure, WORKSPACE_SERVICES } from "./read-tools.adapter.js";
+const BashTool = (description) => Tool.make("bash", { description, parameters: BashParams, success: BashToolResult, failure: Failure, failureMode: "return" }), runsOf = (chunks) => chunks.reduce((runs, chunk) => {
   const last = runs.at(-1);
   if (last !== void 0 && last.stream === chunk.stream)
     runs.splice(-1, 1, { stream: chunk.stream, text: last.text + chunk.text });
   else
     runs.push({ stream: chunk.stream, text: chunk.text });
   return runs;
-}, []), prune = (access, dir, keep) => access.fs.list(dir).pipe(Effect.map((entries) => entries.filter((entry) => entry.kind === "file" && /^bash-.*\.log$/.test(entry.name)).map((entry) => entry.name).sort()), Effect.flatMap((names) => Effect.forEach(names.slice(0, Math.max(0, names.length - keep)), (name) => access.fs.remove(access.path.join(dir, name)), { discard: !0 })), Effect.ignore);
+}, []), prune = (access, dir, keep) => access.fs.list(dir).pipe(Effect.map((entries) => Arr.sort(entries.filter((entry) => entry.kind === "file" && /^bash-.*\.log$/.test(entry.name)).map((entry) => entry.name), Order.String)), Effect.flatMap((names) => Effect.forEach(names.slice(0, Math.max(0, names.length - keep)), (name) => access.fs.remove(access.path.join(dir, name)), { concurrency: 1, discard: !0 })), Effect.ignore({ log: "Warn", message: `the older spill files in ${dir} were not pruned` }));
 export const bashTool = (context) => defineTool({
   tool: BashTool(toolDescriptions(context.config).bash),
+  requires: [...WORKSPACE_SERVICES, Bash],
   handler: (params) => Effect.gen(function* () {
     const { config } = context, access = yield* openWorkspace(context.path), bash = yield* Bash, run = yield* Effect.serviceOption(RunContext), invocation = yield* Effect.service(CurrentToolInvocation), timeoutMs = Math.min(params.timeout === void 0 ? config.bashTimeoutMs : params.timeout * 1000, config.bashMaxTimeoutMs), options = {
       cwd: access.root,
@@ -40,12 +41,12 @@ export const bashTool = (context) => defineTool({
       const next = fitting(spill.bytes, text);
       return (next.piece.length === 0 ? Effect.void : access.fs.append(spill.file, next.piece).pipe(Effect.catch((error) => Effect.logWarning(`bash: could not add to ${spill.file}: ${error.message}`)))).pipe(Effect.as({ ...spill, bytes: next.bytes, cut: next.cut }));
     }, over = (state) => state.bytes - state.crlf - 1 > config.maxBytes || state.breaks > config.maxLines, step = (state, group) => Effect.gen(function* () {
-      const chunks = group.filter(isChunk);
-      yield* Effect.forEach(runsOf(chunks), (current) => publishToolProgress(current.stream, current.text), { discard: !0 });
+      const chunks = group.filter(BashEvent.guards.BashChunk);
+      yield* Effect.forEach(runsOf(chunks), (current) => publishToolProgress(current.stream, current.text), { concurrency: 1, discard: !0 });
       const text = chunks.map((chunk) => chunk.text).join(""), bytes = state.bytes + utf8Length(text), breaks = state.breaks + (text.split(`
 `).length - 1), crlf = state.crlf + (text.split(`\r
 `).length - 1) + (state.tail.endsWith("\r") && text.startsWith(`
-`) ? 1 : 0), exit = Option.orElse(Option.fromNullishOr(group.find(isExit)), () => state.exit), base = { tail: (state.tail + text).slice(-(config.maxBytes + 2)), bytes, breaks, crlf, open: text.length === 0 ? state.open : !text.endsWith(`
+`) ? 1 : 0), exit = Option.orElse(Option.fromNullishOr(group.find(BashEvent.guards.BashExit)), () => state.exit), base = { tail: (state.tail + text).slice(-(config.maxBytes + 2)), bytes, breaks, crlf, open: text.length === 0 ? state.open : !text.endsWith(`
 `), exit };
       if (Option.isSome(state.spill))
         return { ...base, whole: Option.none(), spill: Option.some(yield* addToSpill(state.spill.value, text)) };
@@ -67,6 +68,6 @@ export const bashTool = (context) => defineTool({
       durationMs: Option.match(gathered.exit, { onNone: () => ended - started, onSome: (exit) => exit.durationMs })
     };
   }),
-  view: { version: "1", render: renderBash, compact: compactBash },
+  view: { version: "2", render: renderBash, compact: compactBash },
   annotations: { permissions: [WORKSPACE_PERMISSIONS.exec], pollable: !0 }
 });

package/dist/bash.adapter.d.ts

@@ -1,8 +1,47 @@
-import { Effect, Layer } from "effect";
-import type { Context } from "effect";
+import type { Readable } from "node:stream";
+import { Cause, Effect, Layer, Option, Queue, Stream } from "effect";
+import type { Context, Scope } from "effect";
 import { Bash, BashError } from "@xandreed/core";
+import type { BashChunk, BashEvent, BashExit, BashOptions } from "@xandreed/core";
 import type { BashLiveOptions } from "./local-system.entity.js";
 type BashShape = Context.Service.Shape<typeof Bash>;
+/**
+ * The most events a command's stream holds before the command is made to
+ * wait: a pipe read is at most 64 KB on Node, so about 1 MB of output.
+ */
+export declare const OUTPUT_BUFFER = 16;
+/** How a command's output pipes feed its stream (`relayOutput`). */
+export interface OutputRelay {
+    /** Read `pipe` as `name`: UTF-8, a character split between reads arriving whole; an error on it fails the stream. */
+    readonly attach: (name: BashChunk["stream"], pipe: Readable) => void;
+    /** Stop pausing the pipes: what is left of the output is read at once. */
+    readonly flow: () => void;
+    /** The decoders' last characters, then `exit`, after everything before them; the stream ends after the exit. */
+    readonly finish: (exit: BashExit) => void;
+}
+/**
+ * The bridge from a command's output pipes to its stream's buffer (`queue`,
+ * which holds at most `OUTPUT_BUFFER` events). An event goes straight in
+ * while there is room and nothing waits before it. Otherwise it waits, in
+ * arrival order, and the pipe it came from is paused, so the command blocks
+ * on a full pipe instead of its output piling up in memory; a fiber of the
+ * stream's scope moves waiting events in as the reader takes them, and
+ * resumes their pipes. `flow` ends the pausing, for once the command has
+ * exited (what is left then is the pipes' content, and whatever a
+ * background process writes in `exitGraceMs`). An error on a pipe fails the
+ * stream with `SpawnFailed`.
+ */
+export declare const relayOutput: (queue: Queue.Queue<{
+    readonly _tag: "BashChunk";
+    readonly stream: "stdout" | "stderr";
+    readonly text: string;
+} | {
+    readonly _tag: "BashExit";
+    readonly termination: "interrupted" | "exit" | "signal" | "timeout";
+    readonly exitCode: Option.Option<number>;
+    readonly signal: Option.Option<string>;
+    readonly durationMs: number;
+}, BashError | Cause.Done<void>>) => Effect.Effect<OutputRelay, never, Scope.Scope>;
 /**
  * Commands on the local machine through `node:child_process`, for Node and
  * Bun: `<shell> -c <command>`, detached into a process group of its own, in
@@ -12,18 +51,31 @@ type BashShape = Context.Service.Shape<typeof Bash>;
  * `ShellMissing`. Each command checks its `cwd` first (`CwdMissing`); its
  * stdin is written and closed (a command that never reads it is fine), its
  * stdout and stderr decoded as UTF-8 per stream, a character split between
- * reads arriving whole. A timeout, or a caller that stops reading before
+ * reads arriving whole. While the command runs, its output is read only as
+ * fast as the stream is (`relayOutput`): on Node a reader that falls behind
+ * holds the command back on a full pipe, so output is never gathered
+ * without bound (Bun reads a child's pipes ahead into its own memory, the
+ * reader notwithstanding). A timeout, or a caller that stops reading before
  * the end, kills the whole group; with `killBackground` (the default) so
  * does the command's return. The stream ends once the command has exited
  * and its output has closed, or `exitGraceMs` after the exit if something
  * still holds the output open; the adapter then closes its end of the
  * output pipes, so a background process kept with `killBackground: false`
  * that still writes to them gets `EPIPE` or dies of `SIGPIPE` unless it was
- * started with its own output (`cmd > log 2>&1 &`). Output is buffered
- * without bound until it is read. POSIX only (Linux and macOS): it relies
- * on process groups. Passes `bashConformance` on Bun and Node.
+ * started with its own output (`cmd > log 2>&1 &`). POSIX only (Linux and
+ * macOS): it relies on process groups. Passes `bashConformance` on Bun and
+ * Node (on Bun without the hold-back half of `backpressure`).
+ */
+export declare const makeBash: (options?: BashLiveOptions | undefined) => Effect.Effect<{
+    readonly stream: (command: string, options: BashOptions) => Stream.Stream<BashEvent, BashError>;
+    readonly exec: (command: string, options: BashOptions) => Effect.Effect<import("@xandreed/core").BashResult, BashError>;
+}, BashError, never>;
+/** Whether a `Bash` service is one `makeBash` built, so its commands see the same files as `localFileSystem`. */
+export declare const runsOnThisMachine: (bash: BashShape) => boolean;
+/**
+ * The local `Bash` (`makeBash`) as a layer; building it fails with `ShellMissing` when the shell is not installed.
+ *
+ * @public
  */
-export declare const makeBash: (options?: BashLiveOptions) => Effect.Effect<BashShape, BashError>;
-/** The local `Bash` (`makeBash`) as a layer; building it fails with `ShellMissing` when the shell is not installed. */
 export declare const BashLive: (options?: BashLiveOptions) => Layer.Layer<Bash, BashError>;
 export {};

package/dist/bash.adapter.js

@@ -5,13 +5,16 @@ import { Cause, Clock, Deferred, Effect, Layer, MutableRef, Option, Queue, Resul
 import { Bash, BashError, collectBashResult, resolveBashEnv } from "@xandreed/core";
 import { bashExitOf, errorMessageOf, executableCandidates, isClosedInput } from "./local-system.entity.functions.js";
 import { localSystemDefaults } from "./local-system.entity.js";
-const isExecutableFile = (path) => Effect.tryPromise(() => access(path, constants.X_OK)).pipe(Effect.andThen(Effect.tryPromise(() => stat(path))), Effect.map((info) => info.isFile()), Effect.orElseSucceed(() => !1)), resolveShell = (shell, path) => Effect.findFirst(executableCandidates(shell, path), isExecutableFile).pipe(Effect.flatMap(Option.match({
+const isExecutableFile = (path) => Effect.tryPromise(() => access(path, constants.X_OK)).pipe(Effect.andThen(Effect.tryPromise(() => stat(path))), Effect.map((info) => info.isFile()), Effect.tapError(() => Effect.logDebug(`${path} is not an executable file`)), Effect.orElseSucceed(() => !1)), resolveShell = (shell, path) => Effect.findFirst(executableCandidates(shell, path), isExecutableFile).pipe(Effect.flatMap(Option.match({
   onNone: () => Effect.fail(new BashError({
     reason: "ShellMissing",
     message: `no executable ${shell} ${shell.startsWith("/") ? "at that path" : `on the PATH (${Option.getOrElse(path, () => "unset")})`}`
   })),
   onSome: Effect.succeed
-}))), checkCwd = (cwd) => (cwd.startsWith("/") ? Effect.tryPromise(() => stat(cwd)).pipe(Effect.map((info) => info.isDirectory()), Effect.orElseSucceed(() => !1)) : Effect.succeed(!1)).pipe(Effect.flatMap((directory) => directory ? Effect.void : Effect.fail(new BashError({ reason: "CwdMissing", message: `cwd is not an existing absolute directory: ${cwd}` })))), killGroup = (child, exited) => Option.match(Option.fromNullishOr(child.pid), {
+}))), checkCwd = (cwd) => {
+  const missing = () => new BashError({ reason: "CwdMissing", message: `cwd is not an existing absolute directory: ${cwd}` });
+  return cwd.startsWith("/") ? Effect.tryPromise({ try: () => stat(cwd), catch: missing }).pipe(Effect.flatMap((info) => info.isDirectory() ? Effect.void : Effect.fail(missing()))) : Effect.fail(missing());
+}, killGroup = (child, exited) => Option.match(Option.fromNullishOr(child.pid), {
   onNone: () => {
     return;
   },
@@ -21,10 +24,42 @@ const isExecutableFile = (path) => Effect.tryPromise(() => access(path, constant
       Result.try(() => process.kill(pid, "SIGKILL"));
   }
 });
-export const makeBash = (options = {}) => Effect.gen(function* () {
+export const OUTPUT_BUFFER = 16, relayOutput = Effect.fnUntraced(function* (queue) {
+  const waiting = yield* Queue.unbounded(), behind = MutableRef.make(0), flowing = MutableRef.make(!1), pipes = MutableRef.make([]), decoders = { stdout: new TextDecoder, stderr: new TextDecoder }, wait = (event, pipe) => {
+    if (Option.isSome(pipe) && !MutableRef.get(flowing))
+      pipe.value.pause();
+    MutableRef.increment(behind);
+    Queue.offerUnsafe(waiting, { event, pipe });
+  }, deliver = (event, pipe) => {
+    if (MutableRef.get(behind) > 0 || !Queue.offerUnsafe(queue, event))
+      wait(event, Option.some(pipe));
+  }, chunk = (name, text) => text.length === 0 ? Option.none() : Option.some({ _tag: "BashChunk", stream: name, text });
+  yield* Queue.take(waiting).pipe(Effect.flatMap(({ event, pipe }) => Queue.offer(queue, event).pipe(Effect.andThen(Effect.sync(() => {
+    MutableRef.decrement(behind);
+    Option.map(pipe, (readable) => readable.resume());
+    if (event._tag === "BashExit")
+      Queue.endUnsafe(queue);
+  })))), Effect.forever, Effect.forkScoped);
+  return {
+    attach: (name, pipe) => {
+      MutableRef.update(pipes, (all) => [...all, pipe]);
+      pipe.on("data", (bytes) => Option.map(chunk(name, decoders[name].decode(bytes, { stream: !0 })), (event) => deliver(event, pipe)));
+      pipe.on("error", (error) => Queue.failCauseUnsafe(queue, Cause.fail(new BashError({ reason: "SpawnFailed", message: `could not read the command's ${name}: ${errorMessageOf(error)}` }))));
+    },
+    flow: () => {
+      MutableRef.set(flowing, !0);
+      MutableRef.get(pipes).forEach((pipe) => pipe.resume());
+    },
+    finish: (exit) => {
+      Option.map(chunk("stdout", decoders.stdout.decode()), (event) => wait(event, Option.none()));
+      Option.map(chunk("stderr", decoders.stderr.decode()), (event) => wait(event, Option.none()));
+      wait(exit, Option.none());
+    }
+  };
+}), makeBash = Effect.fnUntraced(function* (options = {}) {
   const { shell, killBackground, exitGraceMs } = { ...localSystemDefaults, ...options }, parentEnv = () => options.parentEnv ?? process.env, shellPath = yield* resolveShell(shell, Option.fromNullishOr(parentEnv().PATH)), stream = (command, run) => Stream.callback((queue) => Effect.gen(function* () {
     yield* checkCwd(run.cwd);
-    const clock = yield* Effect.clockWith((current) => Effect.succeed(current)), exited = yield* Deferred.make(), closed = yield* Deferred.make(), finished = MutableRef.make(!1), decoders = { stdout: new TextDecoder, stderr: new TextDecoder }, emit = (name, text) => text.length > 0 && Queue.offerUnsafe(queue, { _tag: "BashChunk", stream: name, text }), started = yield* Clock.currentTimeMillis, child = yield* Effect.acquireRelease(Effect.try({
+    const clock = yield* Effect.clockWith((current) => Effect.succeed(current)), exited = yield* Deferred.make(), closed = yield* Deferred.make(), finished = MutableRef.make(!1), output = yield* relayOutput(queue), started = yield* Clock.currentTimeMillis, child = yield* Effect.acquireRelease(Effect.try({
       try: () => {
         const spawned = spawn(shellPath, ["-c", command], {
           cwd: run.cwd,
@@ -32,8 +67,10 @@ export const makeBash = (options = {}) => Effect.gen(function* () {
           detached: !0,
           stdio: [run.stdin === void 0 ? "ignore" : "pipe", "pipe", "pipe"]
         });
-        spawned.stdout?.on("data", (chunk) => emit("stdout", decoders.stdout.decode(chunk, { stream: !0 })));
-        spawned.stderr?.on("data", (chunk) => emit("stderr", decoders.stderr.decode(chunk, { stream: !0 })));
+        if (spawned.stdout !== null)
+          output.attach("stdout", spawned.stdout);
+        if (spawned.stderr !== null)
+          output.attach("stderr", spawned.stderr);
         spawned.once("error", (error) => Deferred.doneUnsafe(exited, Effect.fail(new BashError({ reason: "SpawnFailed", message: errorMessageOf(error) }))));
         spawned.once("exit", (code, signal) => Deferred.doneUnsafe(exited, Effect.succeed({ code, signal, at: clock.currentTimeMillisUnsafe() })));
         spawned.once("close", () => Deferred.doneUnsafe(closed, Effect.void));
@@ -54,16 +91,22 @@ export const makeBash = (options = {}) => Effect.gen(function* () {
     })));
     if (killBackground)
       killGroup(child, !0);
+    output.flow();
     const drained = yield* Deferred.await(closed).pipe(Effect.timeoutOption(exitGraceMs));
     if (Option.isNone(drained)) {
       child.stdout?.destroy();
       child.stderr?.destroy();
     }
-    emit("stdout", decoders.stdout.decode());
-    emit("stderr", decoders.stderr.decode());
     MutableRef.set(finished, !0);
-    yield* Queue.offer(queue, bashExitOf({ code: end.code, signal: end.signal, timedOut, durationMs: end.at - started }));
-    yield* Queue.end(queue);
-  }));
-  return Bash.of({ stream, exec: (command, run) => collectBashResult(stream(command, run)) });
-}), BashLive = (options = {}) => Layer.effect(Bash, makeBash(options));
+    output.finish(bashExitOf({ code: end.code, signal: end.signal, timedOut, durationMs: end.at - started }));
+  }), { bufferSize: OUTPUT_BUFFER }), local = Bash.of({
+    stream,
+    exec: Effect.fn("bash.exec")(function* (command, run) {
+      return yield* collectBashResult(stream(command, run));
+    })
+  });
+  localShells.add(local);
+  return local;
+});
+const localShells = new WeakSet;
+export const runsOnThisMachine = (bash) => localShells.has(bash), BashLive = (options = {}) => Layer.effect(Bash, makeBash(options));

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

@@ -15,6 +15,10 @@ type Fs = Context.Service.Shape<typeof FileSystem>;
  * `fileSystemConformance` on Bun and Node.
  */
 export declare const localFileSystem: Fs;
-/** The local `FileSystem` (`localFileSystem`) as a layer. */
+/**
+ * The local `FileSystem` (`localFileSystem`) as a layer.
+ *
+ * @public
+ */
 export declare const FileSystemLive: Layer.Layer<FileSystem>;
 export {};

package/dist/file-system.adapter.js

@@ -18,7 +18,7 @@ const refused = (path, reason, message) => new FsError({ path, reason, message }
     return size <= 0 ? Effect.succeed(chunks) : attempt(path, () => handle.read(new Uint8Array(size), 0, size, position)).pipe(Effect.flatMap(({ bytesRead, buffer }) => bytesRead === 0 ? Effect.succeed(chunks) : gather(position === null ? null : position + bytesRead, remaining - bytesRead, [...chunks, buffer.subarray(0, bytesRead)])));
   };
   return gather(offset === 0 ? null : offset, Option.getOrElse(length, () => Number.POSITIVE_INFINITY), []).pipe(Effect.map(joined));
-})), (handle) => Effect.tryPromise(() => handle.close()).pipe(Effect.ignore)), readBytes = (path, range) => {
+})), (handle) => Effect.tryPromise(() => handle.close()).pipe(Effect.ignore({ log: "Warn", message: `the read handle of ${path} did not close` }))), readBytes = (path, range) => {
   const offset = range?.offset ?? 0, length = Option.fromNullishOr(range?.length);
   if (!(Number.isInteger(offset) && offset >= 0 && Option.match(length, { onNone: () => !0, onSome: (count) => Number.isInteger(count) && count >= 0 })))
     return Effect.fail(refused(path, "Invalid", `offset and length must be whole numbers of at least 0, not ${JSON.stringify(range)}`));

package/dist/image-resizer.adapter.d.ts

@@ -0,0 +1,5 @@
+import { Layer } from "effect";
+import { Bash, FileSystem, ImageResizer } from "@xandreed/core";
+import { ImageResizerConfig } from "./image-resizer.entity.js";
+/** Fit images through an optional host CLI; FileSystem and Bash must share a file tree. @public */
+export declare const ImageResizerCliLive: (options?: Partial<ImageResizerConfig>) => Layer.Layer<ImageResizer, import("@xandreed/core").HarnessError, FileSystem | Bash>;

package/dist/image-resizer.adapter.js

@@ -0,0 +1,68 @@
+import { Effect, Layer, Option, Path, Schema } from "effect";
+import { Bash, FileSystem, harnessError, ImageFitTarget, ImageInput, ImageResizeError, ImageResizer, imageSizeOf, mediaFromBytes, mergeOptions, sniffImageType } from "@xandreed/core";
+import { imageOpacityCommand, imageResizeCommand, imageToolProbe, privateDirectoryCommand, privateInputCommand, privately } from "./image-resizer.entity.functions.js";
+import { ImageResizerConfig, imageResizerDefaults, ImageResizeTool } from "./image-resizer.entity.js";
+import { bashEnvironment } from "./workspace-tools.entity.functions.js";
+import { workspaceToolsDefaults } from "./workspace-tools.entity.js";
+const resizeError = (reason, message, cause) => new ImageResizeError({ reason, message, ...cause === void 0 ? {} : { cause } }), succeeded = (result) => result.termination === "exit" && Option.contains(result.exitCode, 0), makeResizer = Effect.fnUntraced(function* (options) {
+  const config = yield* Schema.decodeUnknownEffect(ImageResizerConfig)(mergeOptions(ImageResizerConfig, imageResizerDefaults, options), { onExcessProperty: "error" }).pipe(Effect.mapError((cause) => harnessError("config.options", "the image resizer options do not decode", cause))), fs = yield* FileSystem, bash = yield* Bash, path = yield* Path.Path.pipe(Effect.provide(Path.layer)), environment = bashEnvironment(workspaceToolsDefaults, Option.none()), candidates = config.tool === "auto" ? ImageResizeTool.literals : [config.tool], available = yield* Effect.findFirst(candidates, (tool) => bash.exec(imageToolProbe(tool), { cwd: "/", timeoutMs: Math.min(config.timeoutMs, 5000), ...environment }).pipe(Effect.map(succeeded), Effect.catch((error) => Effect.logDebug("an image conversion tool could not be probed", error).pipe(Effect.as(!1)))));
+  if (Option.isNone(available))
+    return yield* Effect.fail(harnessError("images.unavailable", "no image conversion tool is available; install ImageMagick, libvips or sips, or provide an ImageResizer"));
+  const tool = available.value, temporary = config.tempDir === null ? (yield* bash.exec(`printf '%s' "\${TMPDIR:-/tmp}"`, { cwd: "/", timeoutMs: Math.min(config.timeoutMs, 5000), ...environment }).pipe(Effect.mapError((cause) => harnessError("config.options", "the image resizer could not read TMPDIR; set tempDir", cause)))).stdout : config.tempDir;
+  if (!temporary.startsWith("/") || temporary.includes("\x00"))
+    return yield* Effect.fail(harnessError("config.options", "the image resizer tempDir must be an absolute POSIX directory"));
+  const fit = Effect.fn("images.fit")(function* (image, target) {
+    const input = yield* Schema.decodeUnknownEffect(ImageInput)(image).pipe(Effect.mapError((cause) => resizeError("Unsupported", "the image input does not decode", cause))), bounds = yield* Schema.decodeUnknownEffect(ImageFitTarget)(target).pipe(Effect.mapError((cause) => resizeError("Failed", "the image fit target does not decode", cause))), type = sniffImageType(input.bytes);
+    if (!Option.contains(type, input.mediaType))
+      return yield* Effect.fail(resizeError("Unsupported", "the bytes are not an image of the declared type"));
+    const size = imageSizeOf(input.bytes, input.mediaType);
+    if (Option.isNone(size))
+      return yield* Effect.fail(resizeError("Unsupported", "the image header does not give its dimensions"));
+    const original = size.value;
+    if (input.bytes.length <= bounds.maxBytes && Math.max(original.width, original.height) <= bounds.maxSide)
+      return input.bytes;
+    if (original.width * original.height > config.maxSourcePixels)
+      return yield* Effect.fail(resizeError("Unsupported", `the source image declares ${original.width}x${original.height} pixels, more than the resizer's maxSourcePixels (${config.maxSourcePixels})`));
+    return yield* Effect.scoped(Effect.gen(function* () {
+      const nonce = yield* Effect.sync(() => crypto.randomUUID()), directory = path.join(temporary, `efferent-img-${nonce}`);
+      yield* Effect.addFinalizer(() => fs.remove(directory, { recursive: !0 }).pipe(Effect.catch((error) => error.reason === "NotFound" ? Effect.void : Effect.logWarning("the image conversion temporary directory could not be removed", error))));
+      const created = yield* bash.exec(privateDirectoryCommand(directory), { cwd: temporary, timeoutMs: Math.min(config.timeoutMs, 5000), ...environment }).pipe(Effect.mapError((cause) => resizeError("Failed", "the image conversion directory could not be created", cause)));
+      if (!succeeded(created))
+        return yield* Effect.fail(resizeError("Failed", "the image conversion directory could not be created", created));
+      const written = yield* bash.exec(privateInputCommand("input.img"), { cwd: directory, stdin: input.bytes, timeoutMs: config.timeoutMs, ...environment }).pipe(Effect.mapError((cause) => resizeError("Failed", "the image conversion input could not be written", cause)));
+      if (!succeeded(written))
+        return yield* Effect.fail(resizeError("Failed", "the image conversion input could not be written", written));
+      const convert = (side, jpeg) => Effect.gen(function* () {
+        const output = path.join(directory, jpeg ? "output.jpg" : "output.png"), result = yield* bash.exec(privately(imageResizeCommand(tool, "input.img", jpeg ? "output.jpg" : "output.png", side, jpeg)), { cwd: directory, timeoutMs: config.timeoutMs, ...environment }).pipe(Effect.mapError((cause) => resizeError("Failed", "the image conversion command could not run", cause)));
+        if (!succeeded(result))
+          return yield* Effect.fail(resizeError("Failed", result.termination === "timeout" ? "the image conversion command timed out" : "the image conversion command failed", result));
+        const bytes = yield* fs.readBytes(output).pipe(Effect.mapError((cause) => resizeError("Failed", "the converted image could not be read", cause))), outputType = sniffImageType(bytes), outputSize = Option.flatMap(outputType, (mediaType) => imageSizeOf(bytes, mediaType));
+        if (Option.isNone(outputSize))
+          return yield* Effect.fail(resizeError("Failed", "the converted image header does not give its dimensions"));
+        const actual = outputSize.value;
+        if (!(actual.width <= original.width && actual.height <= original.height || actual.width <= original.height && actual.height <= original.width))
+          return yield* Effect.fail(resizeError("Failed", "the image converter enlarged the source"));
+        if (bytes.length > bounds.maxBytes || Math.max(actual.width, actual.height) > bounds.maxSide)
+          return Option.none();
+        return yield* mediaFromBytes(bytes).pipe(Effect.as(Option.some(bytes)), Effect.mapError((cause) => resizeError("Failed", "the converted image is not valid media", cause)));
+      }), fallback = (side) => Effect.gen(function* () {
+        const command = imageOpacityCommand(tool, "input.img");
+        if (input.mediaType === "image/png" && command.length > 0 ? yield* bash.exec(command, { cwd: directory, timeoutMs: config.timeoutMs, ...environment }).pipe(Effect.map((result) => succeeded(result) && (result.stdout.trim().toLowerCase() === "true" || /hasAlpha:\s*no\b/i.test(result.stdout))), Effect.catch((cause) => Effect.logDebug("the source opacity could not be checked", cause).pipe(Effect.as(!1)))) : !1) {
+          const fitted = yield* convert(side, !0);
+          if (Option.isSome(fitted))
+            return fitted.value;
+        }
+        return yield* Effect.fail(resizeError("CannotFit", "the image could not fit the requested byte and pixel limits"));
+      }), attempt = (side, remaining) => convert(side, input.mediaType === "image/jpeg").pipe(Effect.flatMap(Option.match({
+        onSome: Effect.succeed,
+        onNone: () => {
+          const smaller = Math.max(1, Math.floor(side * 0.75));
+          return remaining > 1 && smaller < side ? attempt(smaller, remaining - 1) : fallback(side);
+        }
+      })));
+      return yield* attempt(Math.min(bounds.maxSide, Math.max(original.width, original.height)), 4);
+    })).pipe(Effect.timeoutOrElse({ duration: config.timeoutMs, orElse: () => Effect.fail(resizeError("Failed", "the image conversion exceeded its time limit")) }));
+  });
+  return ImageResizer.of({ fit });
+});
+export const ImageResizerCliLive = (options = {}) => Layer.effect(ImageResizer, makeResizer(options));

package/dist/image-resizer.entity.d.ts

@@ -0,0 +1,23 @@
+import { Schema } from "effect";
+/** The optional host CLI used to fit images. @public */
+export declare const ImageResizeTool: Schema.Literals<readonly ["magick", "convert", "vips", "sips"]>;
+export type ImageResizeTool = typeof ImageResizeTool.Type;
+/**
+ * Opt-in image conversion through the host's matching FileSystem and Bash.
+ * auto probes once in tool order. tempDir is an existing absolute directory;
+ * null reads the Bash environment's TMPDIR, falling back to /tmp. timeoutMs
+ * bounds one fit, including its conversion attempts (cleanup follows).
+ * maxSourcePixels refuses a source whose header declares more pixels
+ * (width times height) before any converter decodes it, so a small file
+ * that declares a huge canvas cannot hold the host's memory or disk.
+ * @public
+ */
+export declare const ImageResizerConfig: Schema.Struct<{
+    readonly tool: Schema.Literals<readonly ["auto", "magick", "convert", "vips", "sips"]>;
+    readonly tempDir: Schema.NullOr<Schema.String>;
+    readonly timeoutMs: Schema.Int;
+    readonly maxSourcePixels: Schema.Int;
+}>;
+export type ImageResizerConfig = typeof ImageResizerConfig.Type;
+/** @public */
+export declare const imageResizerDefaults: ImageResizerConfig;

package/dist/image-resizer.entity.functions.d.ts

@@ -0,0 +1,15 @@
+import type { ImageResizeTool } from "./image-resizer.entity.js";
+export declare const imageToolProbe: (tool: ImageResizeTool) => string;
+/** A first-frame conversion; every shell word is literal and the box never upscales. */
+export declare const imageResizeCommand: (tool: ImageResizeTool, input: string, output: string, side: number, jpeg?: boolean) => string;
+/** The converter's own opacity check; a backend without one keeps transparency conservatively. */
+export declare const imageOpacityCommand: (tool: ImageResizeTool, input: string) => string;
+/**
+ * Run a command so that what it creates is its owner's alone: directories
+ * 0700, files 0600, whatever the host's umask.
+ */
+export declare const privately: (command: string) => string;
+/** Create the conversion directory, private and new (it fails when the path exists). */
+export declare const privateDirectoryCommand: (directory: string) => string;
+/** Write standard input to a private file in the command's directory. */
+export declare const privateInputCommand: (name: string) => string;

package/dist/image-resizer.entity.functions.js

@@ -0,0 +1,4 @@
+import { Match } from "effect";
+import { shellQuote } from "./shell.entity.functions.js";
+const executable = { magick: "magick", convert: "convert", vips: "vipsthumbnail", sips: "sips" };
+export const imageToolProbe = (tool) => [executable[tool], tool === "magick" || tool === "convert" ? "-version" : "--version"].map(shellQuote).join(" "), imageResizeCommand = (tool, input, output, side, jpeg = !1) => Match.value(tool).pipe(Match.when("magick", () => ["magick", `${input}[0]`, "-coalesce", "-auto-orient", "-strip", "-resize", `${side}x${side}>`, "-quality", "85", output]), Match.when("convert", () => ["convert", `${input}[0]`, "-coalesce", "-auto-orient", "-strip", "-resize", `${side}x${side}>`, "-quality", "85", output]), Match.when("vips", () => ["vipsthumbnail", input, "--size", `${side}x${side}>`, "--path", `${output}[strip${jpeg ? ",Q=85" : ""}]`]), Match.when("sips", () => ["sips", "-s", "format", jpeg ? "jpeg" : "png", ...jpeg ? ["-s", "formatOptions", "85"] : [], "-Z", String(side), input, "--out", output]), Match.exhaustive, (args) => args.map(shellQuote).join(" ")), imageOpacityCommand = (tool, input) => Match.value(tool).pipe(Match.when("magick", () => ["magick", `${input}[0]`, "-format", "%[opaque]", "info:"]), Match.when("convert", () => ["convert", `${input}[0]`, "-format", "%[opaque]", "info:"]), Match.when("vips", () => []), Match.when("sips", () => ["sips", "-g", "hasAlpha", input]), Match.exhaustive, (args) => args.map(shellQuote).join(" ")), privately = (command) => `umask 077 && ${command}`, privateDirectoryCommand = (directory) => privately(["mkdir", "--", directory].map(shellQuote).join(" ")), privateInputCommand = (name) => privately(`cat > ${shellQuote(name)}`);

package/dist/image-resizer.entity.js

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+export const ImageResizeTool = Schema.Literals(["magick", "convert", "vips", "sips"]), ImageResizerConfig = Schema.Struct({
+  tool: Schema.Literals(["auto", ...ImageResizeTool.literals]),
+  tempDir: Schema.NullOr(Schema.String.check(Schema.makeFilter((path) => path.startsWith("/") && !path.includes("\x00") ? !0 : "an absolute POSIX directory"))),
+  timeoutMs: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 600000 })),
+  maxSourcePixels: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 1e9 }))
+}), imageResizerDefaults = { tool: "auto", tempDir: null, timeoutMs: 30000, maxSourcePixels: 1e8 };

package/dist/index.d.ts

@@ -8,5 +8,7 @@ export { SkillsDirectoryConfig, skillsDirectoryDefaults } from "./skills/skills-
 export { ALWAYS_SECTION_ID, SKILLS_CAPABILITY_ID, skillsCapability } from "./skills/skills-directory.entity.functions.js";
 export { loadSkillsDirectory, skillsDirectoryPlugin, SkillsDirectoryPluginLive } from "./skills/skills-directory.adapter.js";
 export { workspaceTools } from "./workspace-tools.adapter.js";
-export { BashParams, BashToolResult, EditParams, EditResult, FindParams, FindResult, GrepLine, GrepParams, GrepResult, LsEntry, LsParams, LsResult, ReadParams, ReadResult, TextEdit, WORKSPACE_PERMISSIONS, WorkspaceSkillName, WorkspaceToolName, workspaceToolSchemas, WorkspaceToolsConfig, workspaceToolsDefaults, WriteParams, WriteResult, } from "./workspace-tools.entity.js";
-export { applyTextEdits, normalizeLine } from "./text-edit.entity.functions.js";
+export { BashParams, BashToolResult, EditParams, EditResult, FindParams, FindResult, GrepLine, GrepParams, GrepResult, GrepUnreadable, LsEntry, LsParams, LsResult, ReadParams, ReadResult, TextEdit, WORKSPACE_PERMISSIONS, WorkspaceSkillName, WorkspaceToolName, workspaceToolSchemas, WorkspaceToolsConfig, workspaceToolsDefaults, WriteParams, WriteResult, } from "./workspace-tools.entity.js";
+export { ImageResizerCliLive } from "./image-resizer.adapter.js";
+export { ImageResizeTool, ImageResizerConfig, imageResizerDefaults } from "./image-resizer.entity.js";
+export { imageResizerPlugin, ImageResizerPluginLive } from "./plugin.adapter.js";

package/dist/index.js

@@ -17,6 +17,7 @@ export {
   GrepLine,
   GrepParams,
   GrepResult,
+  GrepUnreadable,
   LsEntry,
   LsParams,
   LsResult,
@@ -32,4 +33,6 @@ export {
   WriteParams,
   WriteResult
 } from "./workspace-tools.entity.js";
-export { applyTextEdits, normalizeLine } from "./text-edit.entity.functions.js";
+export { ImageResizerCliLive } from "./image-resizer.adapter.js";
+export { ImageResizeTool, ImageResizerConfig, imageResizerDefaults } from "./image-resizer.entity.js";
+export { imageResizerPlugin, ImageResizerPluginLive } from "./plugin.adapter.js";

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

@@ -13,22 +13,29 @@ import { Schema } from "effect";
  * 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.
+ * given or null.
+ *
+ * @public
  */
-export type BashLiveOptions = Partial<LocalSystemConfig> & {
-    readonly parentEnv?: Readonly<Record<string, string | undefined>>;
+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<{

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

@@ -1,8 +1,6 @@
 import { Option, Result } from "effect";
 import type { BashExit, FsReason } from "@xandreed/core";
 import type { ProcessEnd } from "./local-system.entity.js";
-/** The `code` a Node error carries (`ENOENT`, `ERR_FS_EISDIR`, …), when it has one. */
-export declare const errorCodeOf: (error: unknown) => Option.Option<string>;
 /** A thrown value's message, for the `message` of the error it becomes. */
 export declare const errorMessageOf: (error: unknown) => string;
 /**
@@ -12,8 +10,11 @@ export declare const errorMessageOf: (error: unknown) => string;
  * 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`),

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

@@ -1,5 +1,6 @@
 import { Option, Result } from "effect";
-export const errorCodeOf = (error) => typeof error === "object" && error !== null && ("code" in error) && typeof error.code === "string" ? Option.some(error.code) : Option.none(), errorMessageOf = (error) => error instanceof Error ? error.message : String(error);
+import { errorCodeOf } from "@xandreed/core";
+export const errorMessageOf = (error) => error instanceof Error ? error.message : String(error);
 const reasons = new Map([
   ["ENOENT", "NotFound"],
   ["EEXIST", "Exists"],
@@ -17,7 +18,20 @@ const reasons = new Map([
 export const fsReasonOf = (error) => Option.match(errorCodeOf(error), {
   onNone: () => "Io",
   onSome: (code) => reasons.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 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"),

package/dist/local-system.entity.js

@@ -2,8 +2,9 @@ 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 })))
-}), localSystemDefaults = { shell: "bash", killBackground: !0, exitGraceMs: 500 }, ProcessEnd = Schema.Struct({
+  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,