@xandreed/plugin-workspace 0.0.0-stage → 0.14.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.14.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,72 @@
+import { Tool } from "effect/ai";
+import { Clock, Effect, Option, Random, Stream } from "effect";
+import { Bash, 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) => {
+  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);
+export const bashTool = (context) => defineTool({
+  tool: BashTool(toolDescriptions(context.config).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(isChunk);
+      yield* Effect.forEach(runsOf(chunks), (current) => publishToolProgress(current.stream, current.text), { 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(`
+`), 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: "1", render: renderBash, compact: compactBash },
+  annotations: { permissions: [WORKSPACE_PERMISSIONS.exec], pollable: !0 }
+});

package/dist/bash.adapter.d.ts

@@ -0,0 +1,29 @@
+import { Effect, Layer } from "effect";
+import type { Context } from "effect";
+import { Bash, BashError } from "@xandreed/core";
+import type { BashLiveOptions } from "./local-system.entity.js";
+type BashShape = Context.Service.Shape<typeof Bash>;
+/**
+ * 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. 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.
+ */
+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

@@ -0,0 +1,69 @@
+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.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), {
+  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 makeBash = (options = {}) => Effect.gen(function* () {
+  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({
+      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"]
+        });
+        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 })));
+        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);
+    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));

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

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

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

@@ -0,0 +1,20 @@
+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. */
+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)), 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/file-system.adapter.test.d.ts

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+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, 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";

package/dist/index.js

@@ -0,0 +1,35 @@
+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,
+  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";

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

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

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

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

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

@@ -0,0 +1,32 @@
+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);
+const reasons = new Map([
+  ["ENOENT", "NotFound"],
+  ["EEXIST", "Exists"],
+  ["EISDIR", "IsDirectory"],
+  ["ERR_FS_EISDIR", "IsDirectory"],
+  ["ENOTDIR", "NotDirectory"],
+  ["ENOTEMPTY", "NotEmpty"],
+  ["EACCES", "Permission"],
+  ["EPERM", "Permission"],
+  ["EINVAL", "Invalid"],
+  ["ELOOP", "Invalid"],
+  ["ENAMETOOLONG", "Invalid"],
+  ["ERR_INVALID_ARG_VALUE", "Invalid"]
+]);
+export const fsReasonOf = (error) => Option.match(errorCodeOf(error), {
+  onNone: () => "Io",
+  onSome: (code) => reasons.get(code) ?? "Io"
+}), isClosedInput = (error) => Option.match(errorCodeOf(error), { onNone: () => !1, onSome: (code) => code === "EPIPE" || code === "ERR_STREAM_DESTROYED" }), executableCandidates = (name, path) => name.startsWith("/") ? [name] : name.includes("/") || name.length === 0 ? [] : Option.getOrElse(path, () => "").split(":").filter((dir) => dir.startsWith("/")).map((dir) => `${dir.endsWith("/") ? dir.slice(0, -1) : dir}/${name}`), removalPlace = (path) => {
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  return !path.startsWith("/") ? Result.fail(`paths must be absolute: ${path}`) : Option.match(Option.fromNullishOr(segments.at(-1)), {
+    onNone: () => Result.fail("the root directory is never removed"),
+    onSome: (name) => name === "." || name === ".." ? Result.fail(`a path whose last segment is ${name} is never removed: ${path}`) : Result.succeed({ parent: `/${segments.slice(0, -1).join("/")}`, name })
+  });
+}, pathIn = (dir, name) => dir.endsWith("/") ? `${dir}${name}` : `${dir}/${name}`, bashExitOf = (end) => ({
+  _tag: "BashExit",
+  termination: end.code !== null ? "exit" : end.timedOut ? "timeout" : end.signal !== null ? "signal" : "exit",
+  exitCode: Option.fromNullishOr(end.code),
+  signal: Option.fromNullishOr(end.signal),
+  durationMs: end.durationMs
+});

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

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

package/dist/local-system.entity.js

@@ -0,0 +1,11 @@
+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({
+  code: Schema.NullOr(Schema.Int),
+  signal: Schema.NullOr(Schema.String),
+  timedOut: Schema.Boolean,
+  durationMs: Schema.Number
+});

package/dist/plugin.adapter.d.ts

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