@xandreed/plugin-workspace 0.14.0 → 0.15.0

package/dist/ripgrep.entity.functions.d.ts

@@ -0,0 +1,87 @@
+import { Option } from "effect";
+import { RgMessage } from "./ripgrep.entity.js";
+import type { RgText } from "./ripgrep.entity.js";
+import type { GrepLine, GrepParams, WorkspaceToolsConfig } from "./workspace-tools.entity.js";
+export { shellQuote } from "./shell.entity.functions.js";
+/** The pattern goes only to stdin, never into the shell command. */
+export declare const ripgrepCommand: (config: WorkspaceToolsConfig, params: GrepParams, target: string, perFile: number, exclude: ReadonlyArray<string>) => string;
+export declare const rgText: (value: RgText) => string;
+export declare const decodeRgMessage: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Option.Option<{
+    readonly type: "begin";
+    readonly data: {
+        readonly path: {
+            readonly text: string;
+        } | {
+            readonly bytes: string;
+        };
+    };
+} | {
+    readonly type: "match";
+    readonly data: {
+        readonly path: {
+            readonly text: string;
+        } | {
+            readonly bytes: string;
+        };
+        readonly lines: {
+            readonly text: string;
+        } | {
+            readonly bytes: string;
+        };
+        readonly line_number: number;
+    };
+} | {
+    readonly type: "context";
+    readonly data: {
+        readonly path: {
+            readonly text: string;
+        } | {
+            readonly bytes: string;
+        };
+        readonly lines: {
+            readonly text: string;
+        } | {
+            readonly bytes: string;
+        };
+        readonly line_number: number;
+    };
+} | {
+    readonly type: "end";
+    readonly data: {
+        readonly path: {
+            readonly text: string;
+        } | {
+            readonly bytes: string;
+        };
+        readonly binary_offset: number | null;
+    };
+} | {
+    readonly type: "summary";
+    readonly data: {};
+}>;
+export interface RgSearch {
+    readonly lines: ReadonlyArray<GrepLine>;
+    readonly counts: ReadonlyMap<string, number>;
+    readonly skipped: number;
+    readonly truncated: boolean;
+    readonly stopAtEnd: boolean;
+    readonly capped: ReadonlySet<string>;
+    readonly stopped: boolean;
+    readonly messages: number;
+}
+export declare const emptyRgSearch: RgSearch;
+/** Bound kept matches independently of rg's per-file cap (context can exceed it). */
+export declare const foldRgMessage: (state: RgSearch, message: RgMessage, options: {
+    readonly limit: number;
+    readonly perFile: number;
+    readonly lineChars: number;
+    readonly directory?: boolean;
+    readonly display: (path: string) => string;
+}) => RgSearch;
+/** Keep only context surrounding selected matches; rg may send context for capped hits. */
+export declare const rgLines: (state: RgSearch, context: number) => ReadonlyArray<GrepLine>;
+/** Carry a partial JSON line between Bash chunks; decode only complete records. */
+export declare const rgRecords: (buffer: string, chunk: string) => {
+    readonly buffer: string;
+    readonly records: ReadonlyArray<RgMessage>;
+};

package/dist/ripgrep.entity.functions.js

@@ -0,0 +1,62 @@
+import { Option, Schema } from "effect";
+import { RgMessage } from "./ripgrep.entity.js";
+import { clipChars } from "./text-window.entity.functions.js";
+import { shellQuote } from "./shell.entity.functions.js";
+export { shellQuote } from "./shell.entity.functions.js";
+export const ripgrepCommand = (config, params, target, perFile, exclude) => [
+  "rg",
+  "--json",
+  "--no-config",
+  "--sort",
+  "path",
+  "--hidden",
+  "--no-follow",
+  ...config.grepIgnoreFiles ? [] : ["--no-ignore"],
+  "--max-filesize",
+  String(config.maxFileBytes),
+  "--max-count",
+  String(perFile + 1),
+  ...params.context === void 0 ? [] : ["-C", String(params.context)],
+  ...params.ignoreCase ? ["-i"] : [],
+  ...params.literal ? ["-F"] : [],
+  "-f",
+  "-",
+  ...params.glob === void 0 ? [] : [`--glob=${params.glob}`],
+  ...exclude.map((glob) => `--glob=!${glob.replace(/^\.\//, "/")}`),
+  "--",
+  target
+].map(shellQuote).join(" "), rgText = (value) => ("text" in value) ? value.text : value.bytes, decodeRgMessage = Schema.decodeUnknownOption(Schema.fromJsonString(RgMessage)), emptyRgSearch = { lines: [], counts: new Map, skipped: 0, truncated: !1, stopped: !1, stopAtEnd: !1, capped: new Set, messages: 0 }, foldRgMessage = (state, message, options) => {
+  const next = { ...state, messages: state.messages + 1 }, add = (data, match) => {
+    const path = options.display(rgText(data.path)), count = state.counts.get(path) ?? 0, total = [...state.counts.values()].reduce((sum, found) => sum + found, 0), text = rgText(data.lines).replace(/\r?\n$/, ""), row = { path, line: data.line_number, text: clipChars(text, options.lineChars).text, match };
+    if (match && total >= options.limit)
+      return { ...next, lines: [...state.lines, { ...row, match: !1 }], truncated: !0, stopAtEnd: !0, capped: new Set([...state.capped, path]) };
+    if (match && count >= options.perFile)
+      return { ...next, lines: [...state.lines, { ...row, match: !1 }], truncated: !0, capped: new Set([...state.capped, path]) };
+    return {
+      ...next,
+      lines: [...state.lines, row],
+      counts: match ? new Map([...state.counts, [path, count + 1]]) : state.counts
+    };
+  };
+  return RgMessage.match(message, {
+    begin: () => next,
+    match: ({ data }) => add(data, !0),
+    context: ({ data }) => add(data, !1),
+    end: ({ data }) => {
+      if (data.binary_offset === null) {
+        const atLimit = [...state.counts.values()].reduce((sum, count) => sum + count, 0) >= options.limit;
+        return { ...next, stopped: state.stopAtEnd || atLimit, truncated: state.truncated || options.directory === !0 && atLimit };
+      }
+      const path = options.display(rgText(data.path));
+      return { ...next, lines: state.lines.filter((line) => line.path !== path), counts: new Map([...state.counts].filter(([name]) => name !== path)), skipped: state.skipped + 1, stopped: !1, stopAtEnd: !1, capped: new Set([...state.capped].filter((name) => name !== path)), truncated: [...state.capped].some((name) => name !== path) };
+    },
+    summary: () => next
+  });
+}, rgLines = (state, context) => {
+  const shown = new Set(state.lines.filter((line) => line.match).flatMap((hit) => Array.from({ length: context * 2 + 1 }, (_, offset) => `${hit.path}\x00${hit.line - context + offset}`)));
+  return state.lines.filter((line) => shown.has(`${line.path}\x00${line.line}`));
+}, rgRecords = (buffer, chunk) => {
+  const lines = (buffer + chunk).split(`
+`);
+  return { buffer: lines.at(-1) ?? "", records: lines.slice(0, -1).flatMap((line) => Option.toArray(decodeRgMessage(line))) };
+};

package/dist/ripgrep.entity.js

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+export const RgText = Schema.Union([Schema.Struct({ text: Schema.String }), Schema.Struct({ bytes: Schema.StringFromBase64 })]);
+const line = Schema.Struct({ path: RgText, lines: RgText, line_number: Schema.Int.check(Schema.isGreaterThan(0)) });
+export const RgMessage = Schema.Union([
+  Schema.Struct({ type: Schema.Literal("begin"), data: Schema.Struct({ path: RgText }) }),
+  Schema.Struct({ type: Schema.Literal("match"), data: line }),
+  Schema.Struct({ type: Schema.Literal("context"), data: line }),
+  Schema.Struct({ type: Schema.Literal("end"), data: Schema.Struct({ path: RgText, binary_offset: Schema.NullOr(Schema.Int) }) }),
+  Schema.Struct({ type: Schema.Literal("summary"), data: Schema.Struct({}) })
+]).pipe(Schema.toTaggedUnion("type"));

package/dist/shell.entity.functions.d.ts

@@ -0,0 +1,2 @@
+/** One literal POSIX shell argument, including quotes, newlines and metacharacters. */
+export declare const shellQuote: (value: string) => string;

package/dist/shell.entity.functions.js

@@ -0,0 +1 @@
+export const shellQuote = (value) => `'${value.replaceAll("'", "'\\''")}'`;

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

@@ -8,6 +8,8 @@ import { SkillsDirectoryConfig } from "./skills-directory.entity.js";
  * the ids prefixed, the first root winning a clash, issues failing
  * (`strict`) or logged, and the limits checked. What `skillsDirectoryPlugin`
  * contributes; a host that composes capabilities itself can call it.
+ *
+ * @public
  */
 export declare const loadSkillsDirectory: (config: SkillsDirectoryConfig, workspace: string) => Effect.Effect<ReadonlyArray<SkillDefinition>, HarnessError, FileSystem>;
 /**
@@ -46,17 +48,21 @@ export declare const skillsDirectoryPlugin: import("@xandreed/core").TypedPlugin
     readonly alwaysSection: boolean;
     readonly sectionOrder: number;
 }, Capabilities, HarnessError, FileSystem>;
-/** The skills directory as a typed layer: contributes `Capabilities`; requires `FileSystem` (and reads `SessionEnvironment` when present). */
-export declare const SkillsDirectoryPluginLive: (options?: Partial<{
-    readonly roots: readonly string[];
-    readonly required: boolean;
-    readonly strict: boolean;
-    readonly tools: "ignore" | "declared";
-    readonly idPrefix: string;
-    readonly maxReferenceBytes: number;
-    readonly maxSkills: number;
-    readonly maxFiles: number;
-    readonly maxBytes: number;
-    readonly alwaysSection: boolean;
-    readonly sectionOrder: number;
-}> | undefined) => Layer.Layer<Capabilities, HarnessError, FileSystem>;
+/**
+ * The skills directory as a typed layer: contributes `Capabilities`; requires `FileSystem` (and reads `SessionEnvironment` when present).
+ *
+ * @public
+ */
+export declare const SkillsDirectoryPluginLive: (options?: {
+    readonly roots?: readonly string[];
+    readonly required?: boolean;
+    readonly strict?: boolean;
+    readonly tools?: "ignore" | "declared";
+    readonly idPrefix?: string;
+    readonly maxReferenceBytes?: number;
+    readonly maxSkills?: number;
+    readonly maxFiles?: number;
+    readonly maxBytes?: number;
+    readonly alwaysSection?: boolean;
+    readonly sectionOrder?: number;
+} | undefined) => Layer.Layer<Capabilities, HarnessError, FileSystem>;

package/dist/skills/skills-directory.adapter.js

@@ -13,9 +13,9 @@ const rootFailure = (message) => new HarnessError({ code: "skills.root", message
   const files = yield* collectSkillFiles(root, { maxFiles: config.maxFiles, maxBytes: config.maxBytes, maxFileBytes: config.maxReferenceBytes }), tree = readSkillFiles(files, { tools: config.tools, maxReferenceBytes: config.maxReferenceBytes, rootName: basename(root) });
   return Option.some({ root, tree });
 }).pipe(Effect.catchTag("FsError", (error) => Effect.fail(rootFailure(`cannot read the skills root ${root}: ${error.path}: ${error.message}`))));
-export const loadSkillsDirectory = (config, workspace) => Effect.forEach(config.roots, (root) => readRoot(resolve(workspace, root), config)).pipe(Effect.map((roots) => mergeSkillRoots(roots.flatMap(Option.toArray), config.idPrefix)), Effect.flatMap((found) => settleSkills(found, config))), skillsDirectoryPlugin = definePlugin({
+export const loadSkillsDirectory = (config, workspace) => Effect.forEach(config.roots, (root) => readRoot(resolve(workspace, root), config), { concurrency: 1 }).pipe(Effect.map((roots) => mergeSkillRoots(roots.flatMap(Option.toArray), config.idPrefix)), Effect.flatMap((found) => settleSkills(found, config))), skillsDirectoryPlugin = definePlugin({
   id: "@xandreed/plugin-workspace/skills",
-  version: "0.14.0",
+  version: "0.15.0",
   scope: "runtime",
   config: SkillsDirectoryConfig,
   defaults: skillsDirectoryDefaults,

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

@@ -6,7 +6,7 @@ export declare const SkillRoot: Schema.Struct<{
         readonly skills: Schema.$Array<Schema.Struct<{
             readonly directory: Schema.String;
             readonly skill: Schema.Struct<{
-                readonly id: Schema.Trimmed;
+                readonly id: Schema.brand<Schema.Trimmed, "SkillId">;
                 readonly version: Schema.Trimmed;
                 readonly summary: Schema.Trimmed;
                 readonly instructions: Schema.String;
@@ -14,7 +14,7 @@ export declare const SkillRoot: Schema.Struct<{
                 readonly always: Schema.Boolean;
                 readonly permissions: Schema.$Array<Schema.String>;
                 readonly references: Schema.$Array<Schema.Struct<{
-                    readonly id: Schema.Trimmed;
+                    readonly id: Schema.brand<Schema.Trimmed, "SkillReferenceId">;
                     readonly title: Schema.Trimmed;
                     readonly text: Schema.String;
                 }>>;
@@ -31,7 +31,7 @@ export type SkillRoot = typeof SkillRoot.Type;
 /** The skills of every root together, and every issue, its path absolute. */
 export declare const SkillsFound: Schema.Struct<{
     readonly skills: Schema.$Array<Schema.Struct<{
-        readonly id: Schema.Trimmed;
+        readonly id: Schema.brand<Schema.Trimmed, "SkillId">;
         readonly version: Schema.Trimmed;
         readonly summary: Schema.Trimmed;
         readonly instructions: Schema.String;
@@ -39,7 +39,7 @@ export declare const SkillsFound: Schema.Struct<{
         readonly always: Schema.Boolean;
         readonly permissions: Schema.$Array<Schema.String>;
         readonly references: Schema.$Array<Schema.Struct<{
-            readonly id: Schema.Trimmed;
+            readonly id: Schema.brand<Schema.Trimmed, "SkillReferenceId">;
             readonly title: Schema.Trimmed;
             readonly text: Schema.String;
         }>>;
@@ -53,7 +53,7 @@ export declare const SkillsFound: Schema.Struct<{
 export type SkillsFound = typeof SkillsFound.Type;
 /**
  * How `skillsDirectoryPlugin` loads skills from directories of `SKILL.md`
- * files. Flat: plugin defaults merge one level deep.
+ * files. Flat.
  *
  * - `roots`: the directories, absolute or relative to the agent's workspace
  *   (`SessionEnvironment`, else the process's working directory). A skill
@@ -78,6 +78,8 @@ export type SkillsFound = typeof SkillsFound.Type;
  * - `alwaysSection`: render the instructions of the skills marked `always`
  *   in a static system-prompt section (tool discovery activates always-on
  *   skills but never shows their instructions), at `sectionOrder`.
+ *
+ * @public
  */
 export declare const SkillsDirectoryConfig: Schema.Struct<{
     readonly roots: Schema.$Array<Schema.NonEmptyString>;
@@ -93,4 +95,5 @@ export declare const SkillsDirectoryConfig: Schema.Struct<{
     readonly sectionOrder: Schema.Int;
 }>;
 export type SkillsDirectoryConfig = typeof SkillsDirectoryConfig.Type;
+/** @public */
 export declare const skillsDirectoryDefaults: SkillsDirectoryConfig;

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

@@ -7,9 +7,15 @@ import type { SkillRoot, SkillsDirectoryConfig, SkillsFound } from "./skills-dir
  * is `ALWAYS_SECTION_ID`: read several directories with one plugin instance
  * and several `roots`. Two instances would contribute two capabilities, and
  * two sections, with the same id in `context.built` and turn records.
+ *
+ * @public
  */
 export declare const SKILLS_CAPABILITY_ID = "@xandreed/plugin-workspace/skills";
-/** The static section with the always-on skills' instructions. */
+/**
+ * The static section with the always-on skills' instructions.
+ *
+ * @public
+ */
 export declare const ALWAYS_SECTION_ID = "workspace.skills.always";
 /**
  * Every root's skills together, in root order: each id with `idPrefix`
@@ -22,12 +28,61 @@ export declare const mergeSkillRoots: (roots: ReadonlyArray<SkillRoot>, idPrefix
  * `skills.files` naming each one; otherwise each is logged as a warning.
  * More than `maxSkills` fails with `skills.limit`.
  */
-export declare const settleSkills: (found: SkillsFound, config: Pick<SkillsDirectoryConfig, "strict" | "maxSkills">) => Effect.Effect<ReadonlyArray<SkillDefinition>, HarnessError>;
+export declare const settleSkills: (found: {
+    readonly skills: readonly {
+        readonly id: string & import("effect/Brand").Brand<"SkillId">;
+        readonly version: string;
+        readonly summary: string;
+        readonly instructions: string;
+        readonly tools: readonly string[];
+        readonly always: boolean;
+        readonly permissions: readonly string[];
+        readonly references: readonly {
+            readonly id: string & import("effect/Brand").Brand<"SkillReferenceId">;
+            readonly title: string;
+            readonly text: string;
+        }[];
+    }[];
+    readonly issues: readonly {
+        readonly path: string;
+        readonly severity: "error" | "warning";
+        readonly message: string;
+    }[];
+}, config: Pick<{
+    readonly roots: readonly string[];
+    readonly required: boolean;
+    readonly strict: boolean;
+    readonly tools: "ignore" | "declared";
+    readonly idPrefix: string;
+    readonly maxReferenceBytes: number;
+    readonly maxSkills: number;
+    readonly maxFiles: number;
+    readonly maxBytes: number;
+    readonly alwaysSection: boolean;
+    readonly sectionOrder: number;
+}, "strict" | "maxSkills">) => Effect.Effect<readonly {
+    readonly id: string & import("effect/Brand").Brand<"SkillId">;
+    readonly version: string;
+    readonly summary: string;
+    readonly instructions: string;
+    readonly tools: readonly string[];
+    readonly always: boolean;
+    readonly permissions: readonly string[];
+    readonly references: readonly {
+        readonly id: string & import("effect/Brand").Brand<"SkillReferenceId">;
+        readonly title: string;
+        readonly text: string;
+    }[];
+}[], HarnessError, never>;
 /**
  * The always-on skills' instructions as one system-prompt section: tool
  * discovery activates them at every turn's start but lists only the skills
  * that are loaded on demand.
  */
 export declare const alwaysSkillsText: (skills: ReadonlyArray<SkillDefinition>) => Option.Option<string>;
-/** The skills as one capability, with the always-on section when `alwaysSection` is set and some skill is always on. */
+/**
+ * The skills as one capability, with the always-on section when `alwaysSection` is set and some skill is always on.
+ *
+ * @public
+ */
 export declare const skillsCapability: (skills: ReadonlyArray<SkillDefinition>, config: Pick<SkillsDirectoryConfig, "alwaysSection" | "sectionOrder">) => Capability;

package/dist/skills/skills-directory.entity.functions.js

@@ -1,17 +1,17 @@
 import { Effect, Option } from "effect";
-import { canonicalJson, defineCapability, fingerprintOf, HarnessError, skillIssuesText } from "@xandreed/core";
+import { canonicalJson, defineCapability, definePromptSection, fingerprintOf, HarnessError, SkillId, skillIssuesText } from "@xandreed/core";
 export const SKILLS_CAPABILITY_ID = "@xandreed/plugin-workspace/skills", ALWAYS_SECTION_ID = "workspace.skills.always";
 const inRoot = (root, path) => root.endsWith("/") ? `${root}${path}` : `${root}/${path}`, skillFileOf = (root, directory) => inRoot(root, directory === "" ? "SKILL.md" : `${directory}/SKILL.md`);
 export const mergeSkillRoots = (roots, idPrefix) => {
   const merged = roots.reduce((sofar, { root, tree }) => tree.skills.reduce((state, entry) => {
-    const skill = { ...entry.skill, id: `${idPrefix}${entry.skill.id}` }, from = skillFileOf(root, entry.directory), taken = state.skills.find((other) => other.skill.id === skill.id);
+    const skill = { ...entry.skill, id: SkillId.make(`${idPrefix}${entry.skill.id}`) }, from = skillFileOf(root, entry.directory), taken = state.skills.find((other) => other.skill.id === skill.id);
     return taken === void 0 ? { ...state, skills: [...state.skills, { skill, from }] } : { ...state, issues: [...state.issues, { path: from, severity: "error", message: `the skill id ${skill.id} is already loaded from ${taken.from}` }] };
   }, { ...sofar, issues: [...sofar.issues, ...tree.issues.map((found) => ({ ...found, path: inRoot(root, found.path) }))] }), { skills: [], issues: [] });
   return { skills: merged.skills.map((item) => item.skill), issues: merged.issues };
-}, settleSkills = (found, config) => Effect.gen(function* () {
+}, settleSkills = Effect.fn("skills.settle")(function* (found, config) {
   if (config.strict && found.issues.length > 0)
     return yield* Effect.fail(new HarnessError({ code: "skills.files", message: skillIssuesText(found.issues) }));
-  yield* Effect.forEach(found.issues, (issue) => Effect.logWarning(`skills: ${issue.path}: ${issue.message} (${issue.severity === "error" ? "skill left out" : "read without it"})`), { discard: !0 });
+  yield* Effect.forEach(found.issues, (issue) => Effect.logWarning(`skills: ${issue.path}: ${issue.message} (${issue.severity === "error" ? "skill left out" : "read without it"})`), { concurrency: 1, discard: !0 });
   if (found.skills.length > config.maxSkills)
     return yield* Effect.fail(new HarnessError({ code: "skills.limit", message: `found ${found.skills.length} skills, more than ${config.maxSkills} (maxSkills)` }));
   return found.skills;
@@ -29,7 +29,7 @@ export const mergeSkillRoots = (roots, idPrefix) => {
 
 `));
 }, skillsCapability = (skills, config) => {
-  const section = Option.filter(alwaysSkillsText(skills), () => config.alwaysSection).pipe(Option.map((text) => ({
+  const section = Option.filter(alwaysSkillsText(skills), () => config.alwaysSection).pipe(Option.map((text) => definePromptSection({
     id: ALWAYS_SECTION_ID,
     version: fingerprintOf(text),
     tier: "static",

package/dist/text-edit.entity.functions.js

@@ -7,7 +7,7 @@ const label = (index, count) => count === 1 ? "oldText" : `edit ${index + 1}'s o
   if (first < 0)
     return Result.succeed(Option.none());
   if (base.indexOf(edit.oldText, first + 1) >= 0)
-    return Result.fail(failure("Ambiguous", `${label(index, count)} appears ${Math.max(2, base.split(edit.oldText).length - 1)} times; add surrounding lines so it appears exactly once`));
+    return Result.fail(failure("AmbiguousMatch", `${label(index, count)} appears ${Math.max(2, base.split(edit.oldText).length - 1)} times; add surrounding lines so it appears exactly once`));
   return Result.succeed(Option.some({ index, start: first, end: first + edit.oldText.length, newText: edit.newText, normalized: !1 }));
 }, normalizedSpan = (base, edit, index, count) => {
   const withBreak = edit.oldText.endsWith(`
@@ -20,7 +20,7 @@ const label = (index, count) => count === 1 ? "oldText" : `edit ${index + 1}'s o
   if (start === void 0)
     return Result.succeed(Option.none());
   if (others.length > 0)
-    return Result.fail(failure("Ambiguous", `${label(index, count)} matches ${starts.length} places once whitespace and quotes are normalised; add surrounding lines so it matches exactly once`));
+    return Result.fail(failure("AmbiguousMatch", `${label(index, count)} matches ${starts.length} places once whitespace and quotes are normalised; add surrounding lines so it matches exactly once`));
   const lineStart = (line) => lines.slice(0, line).reduce((total, text) => total + text.length + 1, 0), after = start + wanted.length, lastLine = lines[after - 1] ?? "", end = withBreak ? Math.min(base.length, lineStart(after)) : lineStart(after) - 1 - (lastLine.endsWith("\r") ? 1 : 0);
   return Result.succeed(Option.some({ index, start: lineStart(start), end, newText: edit.newText, normalized: !0 }));
 }, spanOf = (base, edit, index, count, fuzzy) => {
@@ -42,7 +42,7 @@ export const applyTextEdits = (original, edits, options) => {
     const ordered = [...spans].sort((left, right) => left.start - right.start), clash = ordered.findIndex((span, at) => at > 0 && span.start < (ordered[at - 1]?.end ?? 0));
     if (clash > 0) {
       const [first, second] = [ordered[clash - 1]?.index ?? 0, ordered[clash]?.index ?? 0].sort((left, right) => left - right);
-      return Result.fail(failure("Overlap", `edits ${(first ?? 0) + 1} and ${(second ?? 0) + 1} change overlapping text; merge them into one edit`));
+      return Result.fail(failure("OverlappingEdits", `edits ${(first ?? 0) + 1} and ${(second ?? 0) + 1} change overlapping text; merge them into one edit`));
     }
     const built = ordered.reduce((state, span) => ({ text: state.text + base.slice(state.at, span.start) + span.newText, at: span.end }), { text: "", at: 0 }), after = built.text + base.slice(built.at);
     if (after === base)

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

@@ -9,6 +9,13 @@ import type { FileSearch } from "./text-search.entity.js";
  * number of times (`(\d+\.){3}`) is not counted.
  */
 export declare const repeatsRepetition: (source: string) => boolean;
+/**
+ * The pattern, refused (`InvalidPattern`) when it holds a line break: `grep`
+ * matches one line at a time, so the builtin engine would find nothing and
+ * ripgrep, which reads its patterns one per line from stdin, would search
+ * for each line of it on its own. Both engines refuse it alike.
+ */
+export declare const singleLinePattern: (pattern: string) => Result.Result<string, Failure>;
 /**
  * The expression `grep` matches with: the pattern as a JavaScript regular
  * expression, or, with `literal`, as plain text; `ignoreCase` ignores

package/dist/text-search.entity.functions.js

@@ -11,10 +11,10 @@ export const repeatsRepetition = (source) => (source.match(tokenPattern) ?? []).
   if (isQuantifier(token) && unbounded(token))
     return { groups: [...scan.groups.slice(0, -1), !0], closedRepeating: !1, nested: scan.nested || scan.closedRepeating };
   return { ...scan, closedRepeating: !1 };
-}, { groups: [!1], closedRepeating: !1, nested: !1 }).nested, compilePattern = (pattern, options) => {
+}, { groups: [!1], closedRepeating: !1, nested: !1 }).nested, singleLinePattern = (pattern) => /[\r\n]/.test(pattern) ? Result.fail(failure("InvalidPattern", "the pattern contains a line break, but grep matches one line at a time; search for a single line of the text instead")) : Result.succeed(pattern), compilePattern = (pattern, options) => {
   const source = options.literal ? pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") : pattern, compiled = Result.try({
     try: () => new RegExp(source, options.ignoreCase ? "i" : ""),
-    catch: (error) => failure("InvalidPattern", `${pattern} is not a valid regular expression (${error instanceof Error ? error.message : String(error)}); pass literal: true to search for it as text`)
+    catch: (error) => failure("InvalidPattern", `${pattern} is not a valid regular expression; the engine says: ${error instanceof Error ? error.message : String(error)}. Pass literal: true to search for it as text`)
   });
   return Result.flatMap(compiled, (regex) => !options.literal && repeatsRepetition(source) ? Result.fail(failure("InvalidPattern", `${pattern} repeats a group that itself repeats (as in (a+)+), which can take exponential time on some lines; rewrite it without the nested repetition, or search with bash (grep -E, rg)`)) : Result.succeed(regex));
 }, searchText = (text, pattern, options) => {

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

@@ -1,4 +1,20 @@
 import { Schema } from "effect";
+/** Whether the file tools may only read a root, or may also change it. */
+export declare const WorkspaceAccessMode: Schema.Literals<readonly ["read", "write"]>;
+export type WorkspaceAccessMode = typeof WorkspaceAccessMode.Type;
+/** An extra file-tool root, absolute or relative to the session's workspace. */
+export declare const WorkspaceAllowedRoot: Schema.Struct<{
+    readonly path: Schema.NonEmptyString;
+    readonly access: Schema.Literals<readonly ["read", "write"]>;
+}>;
+export type WorkspaceAllowedRoot = typeof WorkspaceAllowedRoot.Type;
+/** An allowed root, resolved on the same file system as the workspace. */
+export declare const AllowedRoot: Schema.Struct<{
+    readonly root: Schema.String;
+    readonly lexicalRoot: Schema.String;
+    readonly access: Schema.Literals<readonly ["read", "write"]>;
+}>;
+export type AllowedRoot = typeof AllowedRoot.Type;
 /**
  * A path a tool was given, resolved in the workspace: `path` is where the
  * tool acts (absolute, every link on the way resolved, through the nearest
@@ -18,5 +34,10 @@ export type WorkspaceTarget = typeof WorkspaceTarget.Type;
 export declare const WorkspaceRoot: Schema.Struct<{
     readonly root: Schema.String;
     readonly lexicalRoot: Schema.String;
+    readonly roots: Schema.$Array<Schema.Struct<{
+        readonly root: Schema.String;
+        readonly lexicalRoot: Schema.String;
+        readonly access: Schema.Literals<readonly ["read", "write"]>;
+    }>>;
 }>;
 export type WorkspaceRoot = typeof WorkspaceRoot.Type;

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

@@ -1,43 +1,73 @@
 import { Effect, Option, Result } from "effect";
 import type { Context, Path } from "effect";
 import { FileSystem, FsError, SessionEnvironment } from "@xandreed/core";
-import type { Failure } from "@xandreed/core";
-import type { WorkspaceRoot, WorkspaceTarget } from "./workspace-path.entity.js";
+import type { Failure, FsReason } from "@xandreed/core";
+import type { WorkspaceAccessMode, WorkspaceAllowedRoot, WorkspaceRoot, WorkspaceTarget } from "./workspace-path.entity.js";
 type Fs = Context.Service.Shape<typeof FileSystem>;
 /** The workspace a call works in (`WorkspaceRoot`), with the file system and path functions it uses. */
 export type WorkspaceAccess = WorkspaceRoot & {
     readonly fs: Fs;
     readonly path: Path.Path;
 };
-/** A file-system failure as the model reads it: what went wrong with the path it gave. */
+/**
+ * A file-system failure as the model reads it: what went wrong with the path
+ * it gave, in words, by the failure's reason. Never the backend's message,
+ * which names host paths the model never gave.
+ */
 export declare const fsFailure: (display: string) => (error: FsError) => Failure;
+/** The workspace directory cannot be opened: why, in words, never the reason's name or the backend's message (it names the host's path). */
+export declare const workspaceMissing: (reason: FsReason) => Failure;
 /** Whether `path` is `root` or below it. */
 export declare const isWithin: (root: string, path: string) => boolean;
 /**
  * Open the workspace of the call: `SessionEnvironment.workspace` made
  * absolute (against the process's directory) and resolved by the file
  * system; one that cannot be resolved fails with `WorkspaceMissing`.
+ * Extra roots are resolved against it for this call. An extra root that
+ * cannot be opened as a directory is logged and left out.
  */
-export declare const openWorkspace: (path: Path.Path) => Effect.Effect<WorkspaceAccess, Failure, FileSystem | SessionEnvironment>;
+export declare const openWorkspace: (path: Path.Path, options?: {
+    readonly roots: ReadonlyArray<WorkspaceAllowedRoot>;
+    readonly workspaceAccess: WorkspaceAccessMode;
+} | undefined) => Effect.Effect<WorkspaceAccess, {
+    readonly error: string;
+    readonly message: string;
+}, FileSystem | SessionEnvironment>;
+/** Whether a real path is inside any root the file tools may read. */
+export declare const withinAnyRoot: (access: WorkspaceAccess, path: string) => boolean;
 /** How a path appears to the model: relative to the root (`.` for the root itself), or absolute outside it. */
 export declare const displayOf: (access: WorkspaceAccess, absolute: string) => string;
 /**
  * Resolve a path a tool was given: relative to the workspace root, or
- * absolute. With `confine`, a path written outside the root is refused
+ * absolute. With `confine`, a path written outside every allowed root is refused
  * before anything is read, and so is one whose real location (links
- * resolved, through the nearest existing ancestor) is outside it
- * (`OutsideWorkspace`). This is a guardrail against mistakes, not a
+ * resolved, through the nearest existing ancestor) is outside all roots
+ * (`OutsideWorkspace`). A write into a read root fails with `ReadOnly`;
+ * the most specific real root decides access. With confinement off these
+ * restrictions are disabled. This is a guardrail against mistakes, not a
  * sandbox: what a path names can change between this check and its use.
  */
 export declare const resolveTarget: (access: WorkspaceAccess, input: string, options: {
     readonly confine: boolean;
-}) => Effect.Effect<WorkspaceTarget, Failure>;
+    readonly intent?: WorkspaceAccessMode;
+}) => Effect.Effect<{
+    readonly path: string;
+    readonly display: string;
+}, {
+    readonly error: string;
+    readonly message: string;
+}, never>;
 /** A compiled `protect` glob: the pattern, and whether a path relative to the root matches it. */
 export interface ProtectRule {
     readonly glob: string;
     readonly matches: (relative: string) => boolean;
 }
-/** Compile `protect` globs (dot entries included); fails with the first pattern that does not compile. */
+/**
+ * Compile `protect` globs (dot entries included); fails with the first
+ * pattern that does not compile. A rule also matches a path that differs
+ * from it only in letter case, so a case-insensitive file system cannot
+ * reach a protected file (`.GIT/config`) through another spelling.
+ */
 export declare const compileProtect: (globs: ReadonlyArray<string>) => Result.Result<ReadonlyArray<ProtectRule>, string>;
 /**
  * The `exclude` globs as a walk from a directory must be given them, the