@xandreed/plugin-workspace 0.0.0-stage → 0.15.0

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

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

package/dist/workspace-path.entity.js

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

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

@@ -0,0 +1,66 @@
+import { Effect } from "effect";
+import type { Scope } from "effect";
+import { HarnessError } from "@xandreed/core";
+import type { Capability } from "@xandreed/core";
+/**
+ * The workspace tools as one capability, for the workspace in each call's
+ * `SessionEnvironment`, over each call's `FileSystem` and `Bash`: `read`,
+ * `ls`, `find` and `grep` (skill `workspace.read`, read-only), `write` and
+ * `edit` (`workspace.edit`, needing `fs.write`) and `bash`
+ * (`workspace.shell`, needing `shell.exec`), plus the
+ * `workspace.environment` prompt section, which reads the same services as
+ * the tools, where the turn renders it. Built once (in a scope, which
+ * holds the per-file write locks): `bash` and its skill are left out, with
+ * a warning, when there is no `Bash` service here; `protect` and `exclude`
+ * globs that do not compile fail with `config.options` (through the plugin,
+ * `WorkspaceToolsConfig` refuses them already when its options are
+ * decoded, so a graph refuses them before activating anything). Tools are never
+ * given guidance as skill instructions: it is in their descriptions and the
+ * section, since an always-on skill's instructions never reach the model.
+ * Ripgrep requires FileSystem and Bash to see the same file tree, so
+ * `grepEngine: "auto"` uses it only when both, here, are this machine's
+ * (`localFileSystem` and a `makeBash` shell, as `localSystemPlugin`
+ * provides); with any other pair (an in-memory file system, a container's
+ * shell, a wrapper) it selects builtin without probing. A host whose pair
+ * shares a tree selects `ripgrep` itself.
+ *
+ * @public
+ */
+export declare const workspaceTools: (config: {
+    readonly tools: readonly ("find" | "write" | "read" | "grep" | "bash" | "ls" | "edit")[];
+    readonly always: readonly ("read" | "edit" | "shell")[];
+    readonly confine: boolean;
+    readonly workspaceAccess: "write" | "read";
+    readonly roots: readonly {
+        readonly path: string;
+        readonly access: "write" | "read";
+    }[];
+    readonly protect: readonly string[];
+    readonly exclude: readonly string[];
+    readonly maxLines: number;
+    readonly maxBytes: number;
+    readonly lsEntries: number;
+    readonly findResults: number;
+    readonly grepMatches: number;
+    readonly grepLineChars: number;
+    readonly grepEngine: "auto" | "ripgrep" | "builtin";
+    readonly grepTimeoutMs: number;
+    readonly grepIgnoreFiles: boolean;
+    readonly maxFileBytes: number;
+    readonly readImages: boolean;
+    readonly imageMaxSide: number;
+    readonly fuzzyEdit: boolean;
+    readonly bashTimeoutMs: number;
+    readonly bashMaxTimeoutMs: number;
+    readonly bashEnv: {
+        readonly [x: string]: string;
+    };
+    readonly bashInheritEnv: boolean;
+    readonly bashEnvAllow: readonly string[];
+    readonly bashSessionEnv: boolean;
+    readonly spillDir: string | null;
+    readonly spillKeep: number;
+    readonly progressMs: number;
+    readonly environmentSection: boolean;
+    readonly sectionOrder: number;
+}) => Effect.Effect<Capability, HarnessError, Scope.Scope>;

package/dist/workspace-tools.adapter.js

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