@xandreed/plugin-workspace 0.0.0-stage → 0.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xand Reed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @xandreed/plugin-workspace
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Efferent composable agent framework, 0.15.0. Node 24 or Bun.
+
+Documentation: https://github.com/xandreeddev/efferent

package/dist/bash-tool.adapter.d.ts

@@ -0,0 +1,15 @@
+import type { RegisteredTool } from "@xandreed/core";
+import type { WorkspaceToolContext } from "./read-tools.adapter.js";
+/**
+ * `bash`: run a command in the workspace root through the `Bash` service of
+ * the call. Output is published as it comes (`tool.progress`: gathered for
+ * `progressMs`, then one event per run of output from one stream), and
+ * folded into a tail the model is shown: the last `maxLines` lines within
+ * `maxBytes`. Once the output is longer than that, it goes to a file under
+ * `spillDir` (named by time and call), whose path the result gives, up to
+ * `maxFileBytes` (what `read` opens; past that nothing more is saved, and
+ * the result says `fullOutputCut`); the newest `spillKeep` files are kept.
+ * A non-zero exit, a signal and a timeout are results; only a command that
+ * could not run at all is a failure.
+ */
+export declare const bashTool: (context: WorkspaceToolContext) => RegisteredTool;

package/dist/bash-tool.adapter.js

@@ -0,0 +1,73 @@
+import { Tool } from "effect/ai";
+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, 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) => 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,
+      ...bashEnvironment(config, Option.map(run, (current) => ({ sessionId: String(current.session.id), runId: current.runId, workspace: access.root }))),
+      timeoutMs,
+      ...params.stdin === void 0 ? {} : { stdin: params.stdin }
+    }, spillDir = Option.map(Option.fromNullishOr(config.spillDir), (dir) => access.path.join(access.root, dir)), started = yield* Clock.currentTimeMillis, tag = yield* Option.match(invocation, {
+      onSome: (call) => Effect.succeed(call.invocationId.replace(/[^A-Za-z0-9._-]/g, "_")),
+      onNone: () => Random.nextIntBetween(0, 2147483647).pipe(Effect.map((value) => value.toString(36)))
+    }), spillName = `bash-${String(started).padStart(15, "0")}-${tag}.log`, fitting = (bytes, text) => {
+      const piece = clipHead(text, Math.max(0, config.maxFileBytes - bytes));
+      return { piece, bytes: bytes + utf8Length(piece), cut: piece.length < text.length };
+    }, startSpill = (text) => Option.match(spillDir, {
+      onNone: () => Effect.succeed(Option.none()),
+      onSome: (dir) => {
+        const file = access.path.join(dir, spillName), first = fitting(0, text);
+        return access.fs.write(file, first.piece, { createParents: !0 }).pipe(Effect.andThen(prune(access, dir, config.spillKeep)), Effect.as(Option.some({ file, bytes: first.bytes, cut: first.cut })), Effect.catch((error) => Effect.logWarning(`bash: the command's whole output could not be saved to ${file}: ${error.message}`).pipe(Effect.as(Option.none()))));
+      }
+    }), addToSpill = (spill, text) => {
+      if (spill.cut || text.length === 0)
+        return Effect.succeed(spill);
+      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(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(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)) };
+      const whole = Option.map(state.whole, (sofar) => sofar + text);
+      if (!over(base) || Option.isNone(whole))
+        return { ...base, whole, spill: Option.none() };
+      return { ...base, whole: Option.none(), spill: yield* startSpill(whole.value) };
+    }), gathered = yield* bash.stream(params.command, options).pipe(Stream.groupedWithin(4096, `${config.progressMs} millis`), Stream.runFoldEffect(() => ({ tail: "", whole: Option.some(""), bytes: 0, breaks: 0, crlf: 0, open: !1, spill: Option.none(), exit: Option.none() }), step), Effect.mapError((error) => failure(error.reason, error.message))), shown = tailText(Option.getOrElse(gathered.whole, () => gathered.tail), config.maxLines, config.maxBytes), truncated = Option.isNone(gathered.whole) || shown.truncated, spill = Option.isSome(gathered.spill) || !truncated ? gathered.spill : yield* Option.match(gathered.whole, { onNone: () => Effect.succeed(Option.none()), onSome: startSpill }), ended = yield* Clock.currentTimeMillis;
+    return {
+      command: params.command,
+      output: shown.text,
+      exitCode: Option.getOrNull(Option.flatMap(gathered.exit, (exit) => exit.exitCode)),
+      signal: Option.getOrNull(Option.flatMap(gathered.exit, (exit) => exit.signal)),
+      termination: Option.match(gathered.exit, { onNone: () => "interrupted", onSome: (exit) => exit.termination }),
+      truncated,
+      totalLines: gathered.breaks + (gathered.open ? 1 : 0),
+      fullOutput: Option.getOrNull(Option.map(spill, (saved) => access.path.relative(access.root, saved.file))),
+      fullOutputCut: Option.exists(spill, (saved) => saved.cut),
+      durationMs: Option.match(gathered.exit, { onNone: () => ended - started, onSome: (exit) => exit.durationMs })
+    };
+  }),
+  view: { version: "2", render: renderBash, compact: compactBash },
+  annotations: { permissions: [WORKSPACE_PERMISSIONS.exec], pollable: !0 }
+});

package/dist/bash.adapter.d.ts

@@ -0,0 +1,81 @@
+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
+ * an environment `resolveBashEnv` builds from `parentEnv`. The shell is
+ * resolved to an absolute path once, here, from the parent `PATH` (so a
+ * command whose own environment has no `PATH` still runs); none fails with
+ * `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. 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 &`). 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 BashLive: (options?: BashLiveOptions) => Layer.Layer<Bash, BashError>;
+export {};

package/dist/bash.adapter.js

@@ -0,0 +1,112 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import { Cause, Clock, Deferred, Effect, Layer, MutableRef, Option, Queue, Result, Stream } from "effect";
+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.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) => {
+  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;
+  },
+  onSome: (pid) => {
+    const group = Result.try(() => process.kill(-pid, "SIGKILL"));
+    if (Result.isFailure(group) && !exited)
+      Result.try(() => process.kill(pid, "SIGKILL"));
+  }
+});
+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), output = yield* relayOutput(queue), started = yield* Clock.currentTimeMillis, child = yield* Effect.acquireRelease(Effect.try({
+      try: () => {
+        const spawned = spawn(shellPath, ["-c", command], {
+          cwd: run.cwd,
+          env: { ...resolveBashEnv(parentEnv(), run) },
+          detached: !0,
+          stdio: [run.stdin === void 0 ? "ignore" : "pipe", "pipe", "pipe"]
+        });
+        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));
+        spawned.stdin?.on("error", (error) => isClosedInput(error) ? !1 : Queue.failCauseUnsafe(queue, Cause.fail(new BashError({ reason: "SpawnFailed", message: `could not write the command's stdin: ${errorMessageOf(error)}` }))));
+        spawned.stdin?.end(run.stdin);
+        return spawned;
+      },
+      catch: (error) => new BashError({ reason: "SpawnFailed", message: errorMessageOf(error) })
+    }), (spawned) => Effect.sync(() => {
+      if (!MutableRef.get(finished))
+        killGroup(spawned, Deferred.isDoneUnsafe(exited));
+      spawned.stdout?.destroy();
+      spawned.stderr?.destroy();
+      spawned.stdin?.destroy();
+    })), awaited = Deferred.await(exited).pipe(Effect.map((end) => ({ end, timedOut: !1 }))), { end, timedOut } = yield* run.timeoutMs === void 0 ? awaited : Deferred.await(exited).pipe(Effect.timeoutOption(run.timeoutMs), Effect.flatMap(Option.match({
+      onSome: (end) => Effect.succeed({ end, timedOut: !1 }),
+      onNone: () => Effect.sync(() => killGroup(child, Deferred.isDoneUnsafe(exited))).pipe(Effect.andThen(awaited), Effect.map(({ end }) => ({ end, timedOut: !0 })))
+    })));
+    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();
+    }
+    MutableRef.set(finished, !0);
+    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

@@ -0,0 +1,24 @@
+import { Layer } from "effect";
+import type { Context } from "effect";
+import { FileSystem } from "@xandreed/core";
+type Fs = Context.Service.Shape<typeof FileSystem>;
+/**
+ * The machine's own file system through `node:fs/promises`, for Node and
+ * Bun. Paths must be absolute (a relative one fails with `Invalid`); every
+ * failure's `reason` comes from the error code (`fsReasonOf`). `glob` is
+ * `walkGlob` over `list`, so it matches what every other backend matches
+ * and never enters a linked directory. `remove` resolves the parent first
+ * and acts on the last name only, so it never follows that name and never
+ * removes the root (nor a path ending in `.` or `..`); `rename` names the
+ * side a failure came from. `stat` reports the permission bits as `mode`.
+ * POSIX only (Linux and macOS): a path must start with `/`. Passes
+ * `fileSystemConformance` on Bun and Node.
+ */
+export declare const localFileSystem: Fs;
+/**
+ * The local `FileSystem` (`localFileSystem`) as a layer.
+ *
+ * @public
+ */
+export declare const FileSystemLive: Layer.Layer<FileSystem>;
+export {};

package/dist/file-system.adapter.js

@@ -0,0 +1,52 @@
+import { appendFile, lstat, mkdir, open, readdir, readFile, realpath, rename, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { Effect, Layer, Option, Result } from "effect";
+import { FileSystem, FsError, walkGlob } from "@xandreed/core";
+import { errorMessageOf, fsReasonOf, pathIn, removalPlace } from "./local-system.entity.functions.js";
+const refused = (path, reason, message) => new FsError({ path, reason, message }), attempt = (path, run) => path.startsWith("/") ? Effect.tryPromise({ try: run, catch: (error) => refused(path, fsReasonOf(error), errorMessageOf(error)) }) : Effect.fail(refused(path, "Invalid", `paths must be absolute: ${path}`)), kindOf = (entry) => entry.isSymbolicLink() ? "symlink" : entry.isFile() ? "file" : entry.isDirectory() ? "directory" : "other", byName = (left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0, bytesOf = (buffer) => new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength), parentsOf = (path) => attempt(path, () => mkdir(dirname(path), { recursive: !0 })).pipe(Effect.asVoid), chunkSize = 65536, joined = (chunks) => {
+  const whole = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.length, 0));
+  chunks.reduce((at, chunk) => {
+    whole.set(chunk, at);
+    return at + chunk.length;
+  }, 0);
+  return whole;
+}, readRange = (path, offset, length) => Effect.acquireUseRelease(attempt(path, () => open(path, "r")), (handle) => attempt(path, () => handle.stat()).pipe(Effect.flatMap((info) => {
+  if (info.isDirectory())
+    return Effect.fail(refused(path, "IsDirectory", `is a directory: ${path}`));
+  const step = Math.max(chunkSize, info.size - offset), gather = (position, remaining, chunks) => {
+    const size = Math.min(remaining, step);
+    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({ 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)}`));
+  return offset === 0 && Option.isNone(length) ? attempt(path, () => readFile(path)).pipe(Effect.map(bytesOf)) : readRange(path, offset, length);
+}, list = (dir) => attempt(dir, () => readdir(dir, { withFileTypes: !0 })).pipe(Effect.map((entries) => entries.map((entry) => ({ name: entry.name, kind: kindOf(entry) })).toSorted(byName))), remove = (path, options) => Result.match(removalPlace(path), {
+  onFailure: (message) => Effect.fail(refused(path, "Invalid", message)),
+  onSuccess: ({ parent, name }) => attempt(path, () => realpath(parent)).pipe(Effect.map((dir) => pathIn(dir, name)), Effect.flatMap((target) => attempt(path, () => lstat(target)).pipe(Effect.flatMap((info) => !info.isDirectory() ? attempt(path, () => unlink(target)) : options?.recursive === !0 ? attempt(path, () => rm(target, { recursive: !0, force: !0 })) : attempt(path, () => rmdir(target)).pipe(Effect.mapError((error) => error.reason === "Exists" ? refused(path, "NotEmpty", error.message) : error))))), Effect.catchIf((error) => error.reason === "NotFound", () => Effect.void))
+}), destinationOnly = new Set(["IsDirectory", "NotEmpty", "Exists"]), eitherSide = new Set(["NotFound", "NotDirectory", "Invalid"]), move = (from, to) => !to.startsWith("/") ? Effect.fail(refused(to, "Invalid", `paths must be absolute: ${to}`)) : attempt(from, () => rename(from, to)).pipe(Effect.catch((error) => {
+  const atTo = new FsError({ path: to, reason: error.reason === "Exists" ? "NotEmpty" : error.reason, message: error.message });
+  return destinationOnly.has(error.reason) ? Effect.fail(atTo) : eitherSide.has(error.reason) ? Effect.tryPromise(() => lstat(from)).pipe(Effect.match({ onFailure: () => error, onSuccess: () => atTo }), Effect.flatMap(Effect.fail)) : Effect.fail(error);
+})), statOf = (path, options) => attempt(path, () => options?.followSymlinks === !1 ? lstat(path) : stat(path)).pipe(Effect.map((info) => ({
+  path,
+  kind: kindOf(info),
+  size: info.size,
+  mtimeMs: info.mtimeMs,
+  mode: Option.some(info.mode & 4095)
+})));
+export const localFileSystem = FileSystem.of({
+  read: (path) => attempt(path, () => readFile(path, "utf8")),
+  readBytes,
+  write: (path, content, options) => (options?.createParents === !0 ? parentsOf(path) : Effect.void).pipe(Effect.andThen(attempt(path, () => writeFile(path, content)))),
+  append: (path, content, options) => (options?.createParents === !0 ? parentsOf(path) : Effect.void).pipe(Effect.andThen(attempt(path, () => appendFile(path, content)))),
+  rename: move,
+  stat: statOf,
+  exists: (path) => attempt(path, () => stat(path)).pipe(Effect.as(!0), Effect.catchIf((error) => error.reason === "NotFound" || error.reason === "NotDirectory", () => Effect.succeed(!1))),
+  list,
+  glob: (pattern, options) => walkGlob(list, pattern, options),
+  mkdir: (dir, options) => attempt(dir, () => mkdir(dir, { recursive: options?.recursive === !0 })).pipe(Effect.asVoid),
+  realPath: (path) => attempt(path, () => realpath(path)),
+  remove
+}), FileSystemLive = Layer.succeed(FileSystem, localFileSystem);

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

@@ -0,0 +1,14 @@
+export { BashLive, makeBash } from "./bash.adapter.js";
+export { FileSystemLive, localFileSystem } from "./file-system.adapter.js";
+export { LocalSystemConfig, localSystemDefaults } from "./local-system.entity.js";
+export type { BashLiveOptions } from "./local-system.entity.js";
+export { fsReasonOf } from "./local-system.entity.functions.js";
+export { localSystemPlugin, LocalSystemPluginLive, workspaceToolsPlugin, WorkspaceToolsPluginLive } from "./plugin.adapter.js";
+export { SkillsDirectoryConfig, skillsDirectoryDefaults } from "./skills/skills-directory.entity.js";
+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, 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

@@ -0,0 +1,38 @@
+export { BashLive, makeBash } from "./bash.adapter.js";
+export { FileSystemLive, localFileSystem } from "./file-system.adapter.js";
+export { LocalSystemConfig, localSystemDefaults } from "./local-system.entity.js";
+export { fsReasonOf } from "./local-system.entity.functions.js";
+export { localSystemPlugin, LocalSystemPluginLive, workspaceToolsPlugin, WorkspaceToolsPluginLive } from "./plugin.adapter.js";
+export { SkillsDirectoryConfig, skillsDirectoryDefaults } from "./skills/skills-directory.entity.js";
+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,
+  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";