@xandreed/plugin-workspace 0.0.0-stage → 0.14.0

package/dist/plugin.adapter.js

@@ -0,0 +1,27 @@
+import { Effect, Layer } from "effect";
+import { Bash, Capabilities, definePlugin, FileSystem, SessionEnvironment } from "@xandreed/core";
+import { BashLive } from "./bash.adapter.js";
+import { FileSystemLive } from "./file-system.adapter.js";
+import { LocalSystemConfig, localSystemDefaults } from "./local-system.entity.js";
+import { workspaceTools } from "./workspace-tools.adapter.js";
+import { WorkspaceToolsConfig, workspaceToolsDefaults } from "./workspace-tools.entity.js";
+export const localSystemPlugin = definePlugin({
+  id: "@xandreed/plugin-workspace/local",
+  version: "0.14.0",
+  scope: "runtime",
+  config: LocalSystemConfig,
+  defaults: localSystemDefaults,
+  provides: [FileSystem, Bash],
+  layer: (config) => Layer.merge(FileSystemLive, BashLive(config))
+}), LocalSystemPluginLive = localSystemPlugin.live, workspaceToolsPlugin = definePlugin({
+  id: "@xandreed/plugin-workspace/tools",
+  version: "0.14.0",
+  scope: "runtime",
+  config: WorkspaceToolsConfig,
+  defaults: workspaceToolsDefaults,
+  requires: [FileSystem, SessionEnvironment],
+  optional: [Bash],
+  provides: [],
+  contributes: [Capabilities],
+  layer: (config) => Layer.effect(Capabilities, workspaceTools(config).pipe(Effect.map((capability) => [capability])))
+}), WorkspaceToolsPluginLive = workspaceToolsPlugin.live;

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

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

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

@@ -0,0 +1,33 @@
+import type { Path, RcMap, Semaphore } from "effect";
+import { Failure } from "@xandreed/core";
+import type { RegisteredTool, Subject } from "@xandreed/core";
+import type { ProtectRule } from "./workspace-path.entity.functions.js";
+import type { WorkspaceToolsConfig } from "./workspace-tools.entity.js";
+/** What every workspace tool is built with: the configuration, the path functions, the compiled `protect` globs and the per-file write locks. */
+export interface WorkspaceToolContext {
+    readonly config: WorkspaceToolsConfig;
+    readonly path: Path.Path;
+    readonly protect: ReadonlyArray<ProtectRule>;
+    readonly locks: RcMap.RcMap<string, Semaphore.Semaphore>;
+}
+export declare const failure: (error: string, message: string) => Failure;
+/** The refusal of a path that is neither a regular file nor a directory: reading a pipe, socket or device could wait forever. */
+export declare const notAFile: (display: string, tool: string) => Failure;
+/** A file the result names, for memory to keep track of; none for a name memory could not store as an id. */
+export declare const fileSubjects: (path: string) => ReadonlyArray<Subject>;
+/** `read`: a window of a text file's lines, an image (`readImages`), or what a binary file is. */
+export declare const readTool: ({ config, path }: WorkspaceToolContext) => RegisteredTool;
+/** `ls`: a directory's entries by name, at most `lsEntries` of them. */
+export declare const lsTool: ({ config, path }: WorkspaceToolContext) => RegisteredTool;
+/** `find`: the files under a directory whose path matches a glob, as paths relative to the workspace root. */
+export declare const findTool: ({ config, path }: WorkspaceToolContext) => RegisteredTool;
+/**
+ * `grep`: the lines of the files under a path (or of one file) that match.
+ * Files come from a walk that never enters links or excluded names; each is
+ * resolved again before it is read and skipped when it leads outside the
+ * workspace, is not a regular file, is larger than `maxFileBytes` or is
+ * binary. Lines are cut to `grepLineChars` before matching. Searching a
+ * directory, one file gives at most a quarter of the limit, so one large
+ * file cannot fill the result.
+ */
+export declare const grepTool: ({ config, path }: WorkspaceToolContext) => RegisteredTool;

package/dist/read-tools.adapter.js

@@ -0,0 +1,100 @@
+import { Tool } from "effect/ai";
+import { Effect, Option, Result } from "effect";
+import { defineTool, Failure } from "@xandreed/core";
+import { compilePattern, searchText } from "./text-search.entity.functions.js";
+import { decodeText, formatBytes, lineWindow, looksBinary } from "./text-window.entity.functions.js";
+import { displayOf, excludesBelow, fsFailure, isWithin, openWorkspace, resolveTarget } from "./workspace-path.entity.functions.js";
+import { FindParams, FindResult, GrepParams, GrepResult, LsParams, LsResult, ReadParams, ReadResult } from "./workspace-tools.entity.js";
+import { binaryRead, compactFind, fileTooLargeHint, compactGrep, compactLs, compactRead, readMedia, renderFind, renderGrep, renderLs, renderRead, toolDescriptions } from "./workspace-tools.entity.functions.js";
+export const failure = (error, message) => ({ error, message }), notAFile = (display, tool) => failure("NotAFile", `${display} is not a regular file (a pipe, socket or device); ${tool} works on regular files only, use bash for it`);
+const walkExcludes = (access, target, excludes) => excludesBelow(excludes, isWithin(access.root, target.path) ? Option.some(access.path.relative(access.root, target.path)) : Option.none());
+export const fileSubjects = (path) => path.length > 0 && path.trim() === path ? [{ kind: "file", id: path, label: Option.none(), data: Option.none() }] : [];
+const ReadTool = (description) => Tool.make("read", { description, parameters: ReadParams, success: ReadResult, failure: Failure, failureMode: "return" }), LsTool = (description) => Tool.make("ls", { description, parameters: LsParams, success: LsResult, failure: Failure, failureMode: "return" }), FindTool = (description) => Tool.make("find", { description, parameters: FindParams, success: FindResult, failure: Failure, failureMode: "return" }), GrepTool = (description) => Tool.make("grep", { description, parameters: GrepParams, success: GrepResult, failure: Failure, failureMode: "return" });
+export const readTool = ({ config, path }) => defineTool({
+  tool: ReadTool(toolDescriptions(config).read),
+  handler: (params) => Effect.gen(function* () {
+    const access = yield* openWorkspace(path), target = yield* resolveTarget(access, params.path, { confine: config.confine }), info = yield* access.fs.stat(target.path).pipe(Effect.mapError(fsFailure(target.display)));
+    if (info.kind === "directory")
+      return yield* Effect.fail(failure("IsDirectory", `${target.display} is a directory; use ls to list it`));
+    if (info.kind !== "file")
+      return yield* Effect.fail(notAFile(target.display, "read"));
+    if (info.size > config.maxFileBytes)
+      return yield* Effect.fail(failure("FileTooLarge", `${target.display} is ${formatBytes(info.size)}, more than the ${formatBytes(config.maxFileBytes)} read loads; ${fileTooLargeHint(target.display, config.readImages)}`));
+    const bytes = yield* access.fs.readBytes(target.path).pipe(Effect.mapError(fsFailure(target.display)));
+    if (looksBinary(bytes))
+      return yield* binaryRead(target.display, bytes, config.readImages);
+    const decoded = decodeText(bytes), window = lineWindow(decoded.text, { offset: params.offset ?? 1, limit: Math.min(params.limit ?? config.maxLines, config.maxLines), maxBytes: config.maxBytes });
+    return yield* Result.match(window, {
+      onFailure: (total) => Effect.fail(failure("OffsetPastEnd", `${target.display} has ${total} line${total === 1 ? "" : "s"}; offset must be at most ${Math.max(1, total)}`)),
+      onSuccess: (lines) => Effect.succeed({
+        _tag: "Text",
+        path: target.display,
+        text: lines.lines.join(`
+`),
+        firstLine: lines.firstLine,
+        lastLine: lines.lastLine,
+        totalLines: lines.totalLines,
+        next: Option.getOrNull(lines.next),
+        clipped: lines.clipped,
+        lossy: decoded.lossy
+      })
+    });
+  }),
+  view: { version: "1", render: renderRead, compact: compactRead, subjects: (result) => fileSubjects(result.path), media: readMedia },
+  annotations: { readOnly: !0 }
+}), lsTool = ({ config, path }) => defineTool({
+  tool: LsTool(toolDescriptions(config).ls),
+  handler: (params) => Effect.gen(function* () {
+    const access = yield* openWorkspace(path), target = yield* resolveTarget(access, params.path ?? ".", { confine: config.confine }), entries = yield* access.fs.list(target.path).pipe(Effect.mapError((error) => error.reason === "NotDirectory" ? failure("NotDirectory", `${target.display} is not a directory; use read to see a file`) : fsFailure(target.display)(error))), limit = Math.min(params.limit ?? config.lsEntries, config.lsEntries);
+    return { path: target.display, entries: entries.slice(0, limit).map((entry) => ({ name: entry.name, kind: entry.kind })), total: entries.length };
+  }),
+  view: { version: "1", render: renderLs, compact: compactLs },
+  annotations: { readOnly: !0 }
+}), findTool = ({ config, path }) => defineTool({
+  tool: FindTool(toolDescriptions(config).find),
+  handler: (params) => Effect.gen(function* () {
+    const access = yield* openWorkspace(path), target = yield* resolveTarget(access, params.path ?? ".", { confine: config.confine }), limit = Math.min(params.limit ?? config.findResults, config.findResults), found = yield* access.fs.glob(params.pattern, { cwd: target.path, exclude: walkExcludes(access, target, config.exclude), dot: !0, onlyFiles: !0, limit }).pipe(Effect.mapError((error) => error.reason === "Invalid" ? failure("InvalidPattern", `${params.pattern}: ${error.message}`) : fsFailure(target.display)(error)));
+    return { pattern: params.pattern, path: target.display, paths: found.paths.map((relative) => displayOf(access, access.path.join(target.path, relative))), truncated: found.truncated };
+  }),
+  view: { version: "1", render: (result) => renderFind(result, config.maxLines, config.maxBytes), compact: compactFind },
+  annotations: { readOnly: !0 }
+}), grepTool = ({ config, path }) => defineTool({
+  tool: GrepTool(toolDescriptions(config).grep),
+  handler: (params) => Effect.gen(function* () {
+    const access = yield* openWorkspace(path), target = yield* resolveTarget(access, params.path ?? ".", { confine: config.confine }), pattern = yield* Effect.fromResult(compilePattern(params.pattern, { literal: params.literal ?? !1, ignoreCase: params.ignoreCase ?? !1 })), info = yield* access.fs.stat(target.path).pipe(Effect.mapError(fsFailure(target.display)));
+    if (info.kind !== "file" && info.kind !== "directory")
+      return yield* Effect.fail(notAFile(target.display, "grep"));
+    const glob = params.glob === void 0 ? "**/*" : params.glob.includes("/") ? params.glob : `**/${params.glob}`, files = info.kind === "file" ? [{ path: target.path, display: target.display }] : yield* access.fs.glob(glob, { cwd: target.path, exclude: walkExcludes(access, target, config.exclude), dot: !0, onlyFiles: !0 }).pipe(Effect.map((found) => found.paths.map((relative) => {
+      const absolute = access.path.join(target.path, relative);
+      return { path: absolute, display: displayOf(access, absolute) };
+    })), Effect.mapError((error) => error.reason === "Invalid" ? failure("InvalidPattern", `glob ${glob}: ${error.message}`) : fsFailure(target.display)(error))), limit = Math.min(params.limit ?? config.grepMatches, config.grepMatches), perFile = files.length > 1 ? Math.max(1, Math.ceil(limit / 4)) : limit, context = params.context ?? 0, skip = (state) => ({ ...state, skipped: state.skipped + 1 }), searched = yield* Effect.reduce(files, () => ({ lines: [], matches: 0, files: 0, skipped: 0, truncated: !1 }), (state, file) => {
+      if (state.matches >= limit)
+        return Effect.succeed({ ...state, truncated: !0 });
+      return Effect.gen(function* () {
+        const real = yield* access.fs.realPath(file.path);
+        if (config.confine && !isWithin(access.root, real))
+          return Option.none();
+        const found = yield* access.fs.stat(real);
+        if (found.kind !== "file" || found.size > config.maxFileBytes)
+          return Option.none();
+        const bytes = yield* access.fs.readBytes(real);
+        return looksBinary(bytes) ? Option.none() : Option.some(bytes);
+      }).pipe(Effect.option, Effect.map((bytes) => Option.match(Option.flatten(bytes), {
+        onNone: () => skip(state),
+        onSome: (content) => {
+          const found = searchText(decodeText(content).text, pattern, { lineChars: config.grepLineChars, context, cap: Math.min(perFile, limit - state.matches) });
+          return {
+            lines: [...state.lines, ...found.lines.map((line) => ({ path: file.display, ...line }))],
+            matches: state.matches + found.matches,
+            files: state.files + (found.matches > 0 ? 1 : 0),
+            skipped: state.skipped,
+            truncated: state.truncated || found.capped
+          };
+        }
+      })));
+    });
+    return { pattern: params.pattern, path: target.display, ...searched };
+  }),
+  view: { version: "1", render: (result, params) => renderGrep(result, (params.context ?? 0) > 0, config.maxLines, config.maxBytes), compact: compactGrep },
+  annotations: { readOnly: !0 }
+});

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

@@ -0,0 +1,62 @@
+import { Effect, Layer } from "effect";
+import { Capabilities, FileSystem, HarnessError } from "@xandreed/core";
+import type { SkillDefinition } from "@xandreed/core";
+import { SkillsDirectoryConfig } from "./skills-directory.entity.js";
+/**
+ * The skills in `config.roots`, each resolved against `workspace` (an
+ * absolute directory) unless absolute, read through the `FileSystem` port:
+ * 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.
+ */
+export declare const loadSkillsDirectory: (config: SkillsDirectoryConfig, workspace: string) => Effect.Effect<ReadonlyArray<SkillDefinition>, HarnessError, FileSystem>;
+/**
+ * Skills from directories of `SKILL.md` files (the Agent Skills layout,
+ * `.agents/skills/<name>/SKILL.md` by default), read once per agent through
+ * the `FileSystem` port and contributed as one capability. Tool discovery
+ * lists them in its catalogue, `load_skill` returns a skill's instructions
+ * and `read_skill_reference` the other files of its directory. A skill id
+ * the host or another plugin also defines fails `Agent.define` with
+ * `skills.duplicate`: set `idPrefix`. Relative roots resolve against the
+ * agent's workspace (`SessionEnvironment`), else the process's working
+ * directory.
+ */
+export declare const skillsDirectoryPlugin: import("@xandreed/core").TypedPlugin<{
+    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;
+}, {
+    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;
+}, 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>;

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

@@ -0,0 +1,30 @@
+import { basename, resolve } from "node:path";
+import { Effect, Layer, Option } from "effect";
+import { Capabilities, collectSkillFiles, definePlugin, FileSystem, HarnessError, readSkillFiles, SessionEnvironment } from "@xandreed/core";
+import { SkillsDirectoryConfig, skillsDirectoryDefaults } from "./skills-directory.entity.js";
+import { mergeSkillRoots, settleSkills, skillsCapability } from "./skills-directory.entity.functions.js";
+const rootFailure = (message) => new HarnessError({ code: "skills.root", message }), readRoot = (root, config) => Effect.gen(function* () {
+  if (!(yield* (yield* FileSystem).exists(root))) {
+    if (config.required)
+      return yield* Effect.fail(rootFailure(`the skills root ${root} does not exist (required)`));
+    yield* Effect.logDebug(`skills: no directory at ${root}; skipped`);
+    return Option.none();
+  }
+  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({
+  id: "@xandreed/plugin-workspace/skills",
+  version: "0.14.0",
+  scope: "runtime",
+  config: SkillsDirectoryConfig,
+  defaults: skillsDirectoryDefaults,
+  requires: [FileSystem],
+  optional: [SessionEnvironment],
+  provides: [],
+  contributes: [Capabilities],
+  layer: (config) => Layer.effect(Capabilities, Effect.gen(function* () {
+    const environment = yield* Effect.serviceOption(SessionEnvironment), workspace = resolve(Option.match(environment, { onNone: () => ".", onSome: (found) => found.workspace })), skills = yield* loadSkillsDirectory(config, workspace);
+    return [skillsCapability(skills, config)];
+  }))
+}), SkillsDirectoryPluginLive = skillsDirectoryPlugin.live;

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

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

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

@@ -0,0 +1,96 @@
+import { Schema } from "effect";
+/** One root as read: its absolute path and the tree of skills in it. */
+export declare const SkillRoot: Schema.Struct<{
+    readonly root: Schema.String;
+    readonly tree: Schema.Struct<{
+        readonly skills: Schema.$Array<Schema.Struct<{
+            readonly directory: Schema.String;
+            readonly skill: Schema.Struct<{
+                readonly id: Schema.Trimmed;
+                readonly version: Schema.Trimmed;
+                readonly summary: Schema.Trimmed;
+                readonly instructions: Schema.String;
+                readonly tools: Schema.$Array<Schema.Trimmed>;
+                readonly always: Schema.Boolean;
+                readonly permissions: Schema.$Array<Schema.String>;
+                readonly references: Schema.$Array<Schema.Struct<{
+                    readonly id: Schema.Trimmed;
+                    readonly title: Schema.Trimmed;
+                    readonly text: Schema.String;
+                }>>;
+            }>;
+        }>>;
+        readonly issues: Schema.$Array<Schema.Struct<{
+            readonly path: Schema.String;
+            readonly severity: Schema.Literals<readonly ["error", "warning"]>;
+            readonly message: Schema.String;
+        }>>;
+    }>;
+}>;
+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 version: Schema.Trimmed;
+        readonly summary: Schema.Trimmed;
+        readonly instructions: Schema.String;
+        readonly tools: Schema.$Array<Schema.Trimmed>;
+        readonly always: Schema.Boolean;
+        readonly permissions: Schema.$Array<Schema.String>;
+        readonly references: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.Trimmed;
+            readonly title: Schema.Trimmed;
+            readonly text: Schema.String;
+        }>>;
+    }>>;
+    readonly issues: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.String;
+        readonly severity: Schema.Literals<readonly ["error", "warning"]>;
+        readonly message: Schema.String;
+    }>>;
+}>;
+export type SkillsFound = typeof SkillsFound.Type;
+/**
+ * How `skillsDirectoryPlugin` loads skills from directories of `SKILL.md`
+ * files. Flat: plugin defaults merge one level deep.
+ *
+ * - `roots`: the directories, absolute or relative to the agent's workspace
+ *   (`SessionEnvironment`, else the process's working directory). A skill
+ *   whose id an earlier root already loaded is left out (an issue). One
+ *   instance with several roots is how to read several directories: the
+ *   capability and section ids are fixed, so two instances would share them.
+ * - `required`: a missing root fails `Agent.define` (`skills.root`); when
+ *   false, a missing root is skipped.
+ * - `strict`: any issue (a `SKILL.md` without frontmatter or description, an
+ *   id taken, a reference over `maxReferenceBytes`, an unreadable value)
+ *   fails `Agent.define` with `skills.files`; when false, each is logged as a
+ *   warning and what it names is left out.
+ * - `tools`: `"ignore"` drops the `tools` each `SKILL.md` declares, so a file
+ *   skill is instructions and references only; `"declared"` keeps them, and
+ *   a tool no capability registers fails `Agent.define` with `skills.tools`.
+ * - `idPrefix`: put before every skill id (`"project."`), for skills whose
+ *   ids clash with the host's or another plugin's (`skills.duplicate`).
+ * - `maxReferenceBytes`: a reference larger than this is left out (it is
+ *   not read, and does not count toward `maxBytes`).
+ * - `maxSkills` (all roots together), `maxFiles` and `maxBytes` (each root's
+ *   files, and bytes of text): more fails `Agent.define` with `skills.limit`.
+ * - `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`.
+ */
+export declare const SkillsDirectoryConfig: Schema.Struct<{
+    readonly roots: Schema.$Array<Schema.NonEmptyString>;
+    readonly required: Schema.Boolean;
+    readonly strict: Schema.Boolean;
+    readonly tools: Schema.Literals<readonly ["declared", "ignore"]>;
+    readonly idPrefix: Schema.String;
+    readonly maxReferenceBytes: Schema.Int;
+    readonly maxSkills: Schema.Int;
+    readonly maxFiles: Schema.Int;
+    readonly maxBytes: Schema.Int;
+    readonly alwaysSection: Schema.Boolean;
+    readonly sectionOrder: Schema.Int;
+}>;
+export type SkillsDirectoryConfig = typeof SkillsDirectoryConfig.Type;
+export declare const skillsDirectoryDefaults: SkillsDirectoryConfig;

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

@@ -0,0 +1,33 @@
+import { Effect, Option } from "effect";
+import { HarnessError } from "@xandreed/core";
+import type { Capability, SkillDefinition } from "@xandreed/core";
+import type { SkillRoot, SkillsDirectoryConfig, SkillsFound } from "./skills-directory.entity.js";
+/**
+ * The id of the capability the skills are contributed in. It is fixed, as
+ * 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.
+ */
+export declare const SKILLS_CAPABILITY_ID = "@xandreed/plugin-workspace/skills";
+/** The static section with the always-on skills' instructions. */
+export declare const ALWAYS_SECTION_ID = "workspace.skills.always";
+/**
+ * Every root's skills together, in root order: each id with `idPrefix`
+ * before it, a skill whose id an earlier root (or an earlier skill) already
+ * loaded left out with an error, and every issue's path made absolute.
+ */
+export declare const mergeSkillRoots: (roots: ReadonlyArray<SkillRoot>, idPrefix: string) => SkillsFound;
+/**
+ * The skills to contribute: with `strict`, any issue fails with
+ * `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>;
+/**
+ * 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. */
+export declare const skillsCapability: (skills: ReadonlyArray<SkillDefinition>, config: Pick<SkillsDirectoryConfig, "alwaysSection" | "sectionOrder">) => Capability;

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

@@ -0,0 +1,45 @@
+import { Effect, Option } from "effect";
+import { canonicalJson, defineCapability, fingerprintOf, HarnessError, 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);
+    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* () {
+  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 });
+  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;
+}), alwaysSkillsText = (skills) => {
+  const always = skills.filter((skill) => skill.always);
+  return always.length === 0 ? Option.none() : Option.some([
+    "## Always-on skills",
+    ...always.map((skill) => [
+      `### ${skill.id}`,
+      skill.instructions.length > 0 ? skill.instructions : skill.summary,
+      skill.references.length === 0 ? "" : `References (read_skill_reference): ${skill.references.map((reference) => `${reference.id} \u2014 ${reference.title}`).join("; ")}`
+    ].filter((line) => line.length > 0).join(`
+`))
+  ].join(`
+
+`));
+}, skillsCapability = (skills, config) => {
+  const section = Option.filter(alwaysSkillsText(skills), () => config.alwaysSection).pipe(Option.map((text) => ({
+    id: ALWAYS_SECTION_ID,
+    version: fingerprintOf(text),
+    tier: "static",
+    order: config.sectionOrder,
+    render: () => Effect.succeed(Option.some(text))
+  })));
+  return defineCapability({
+    id: SKILLS_CAPABILITY_ID,
+    version: fingerprintOf(canonicalJson(skills.map((skill) => [skill.id, skill.version]))),
+    skills,
+    promptSections: Option.toArray(section)
+  });
+};

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

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

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

@@ -0,0 +1,35 @@
+import { Schema } from "effect";
+import { SkillDefinition, SkillFileIssue, SkillTree } from "@xandreed/core";
+export const SkillRoot = Schema.Struct({
+  root: Schema.String,
+  tree: SkillTree
+}), SkillsFound = Schema.Struct({
+  skills: Schema.Array(SkillDefinition),
+  issues: Schema.Array(SkillFileIssue)
+});
+const count = (maximum) => Schema.Int.pipe(Schema.check(Schema.isBetween({ minimum: 1, maximum })));
+export const SkillsDirectoryConfig = Schema.Struct({
+  roots: Schema.Array(Schema.NonEmptyString),
+  required: Schema.Boolean,
+  strict: Schema.Boolean,
+  tools: Schema.Literals(["declared", "ignore"]),
+  idPrefix: Schema.String.check(Schema.isPattern(/^\S*$/)).annotate({ description: "Put before every skill id; no whitespace." }),
+  maxReferenceBytes: count(16777216),
+  maxSkills: count(1e4),
+  maxFiles: count(1e6),
+  maxBytes: count(1073741824),
+  alwaysSection: Schema.Boolean,
+  sectionOrder: Schema.Int
+}), skillsDirectoryDefaults = {
+  roots: [".agents/skills"],
+  required: !1,
+  strict: !1,
+  tools: "ignore",
+  idPrefix: "",
+  maxReferenceBytes: 65536,
+  maxSkills: 200,
+  maxFiles: 2000,
+  maxBytes: 8388608,
+  alwaysSection: !0,
+  sectionOrder: 850
+};

package/dist/text-edit.entity.d.ts

@@ -0,0 +1,32 @@
+import { Schema } from "effect";
+/**
+ * How a text ends its lines: every break is `\r\n` (`crlf`), none has a
+ * `\r` (`lf`), or both kinds appear (`mixed`, matched as it is).
+ */
+export declare const LineEnding: Schema.Literals<readonly ["lf", "crlf", "mixed"]>;
+export type LineEnding = typeof LineEnding.Type;
+/**
+ * Edits applied to a text: `text` is the new text, in the original's line
+ * endings; `before` and `after` are the old and new text with `\n` line
+ * breaks (what a diff compares); `replaced` counts the edits, `normalized`
+ * says whether any was found only after normalising, and
+ * `firstChangedLine` is the 1-based line of the first change.
+ */
+export declare const EditPlan: Schema.Struct<{
+    readonly text: Schema.String;
+    readonly before: Schema.String;
+    readonly after: Schema.String;
+    readonly replaced: Schema.Int;
+    readonly normalized: Schema.Boolean;
+    readonly firstChangedLine: Schema.Int;
+}>;
+export type EditPlan = typeof EditPlan.Type;
+/** Where one edit applies in the original: the span `[start, end)` and what replaces it. */
+export declare const EditSpan: Schema.Struct<{
+    readonly index: Schema.Int;
+    readonly start: Schema.Int;
+    readonly end: Schema.Int;
+    readonly newText: Schema.String;
+    readonly normalized: Schema.Boolean;
+}>;
+export type EditSpan = typeof EditSpan.Type;

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

@@ -0,0 +1,32 @@
+import { Result } from "effect";
+import type { Failure } from "@xandreed/core";
+import type { EditPlan, LineEnding } from "./text-edit.entity.js";
+import type { TextEdit } from "./workspace-tools.entity.js";
+/** How `text` ends its lines (see `LineEnding`). */
+export declare const lineEndingOf: (text: string) => LineEnding;
+/**
+ * A line as the fallback compares it: Unicode compatibility forms folded
+ * (NFKC, which also makes a no-break space a space), curly quotes and
+ * primes made straight, dashes and the minus sign made `-`, runs of
+ * whitespace made one space, and the ends trimmed.
+ */
+export declare const normalizeLine: (line: string) => string;
+/**
+ * Apply edits to a file's text. Every edit is matched against the original,
+ * never against another edit's result: its `oldText` must appear exactly
+ * once (an empty one is refused), or, with `fuzzy`, once over whole lines
+ * after `normalizeLine`. The spans must not overlap. A text whose every
+ * line break is `\r\n` is matched with `\n` breaks (in it and in the edits)
+ * and written back with `\r\n`; a text without `\r` gets the edits' `\r\n`
+ * as `\n`. Edits that leave the text as it was fail with `NoChange`.
+ */
+export declare const applyTextEdits: (original: string, edits: ReadonlyArray<TextEdit>, options: {
+    readonly fuzzy: boolean;
+}) => Result.Result<EditPlan, Failure>;
+/**
+ * The change as a unified diff (`--- path` / `+++ path`), from effect's
+ * `TextDiff` with at most 10 000 edits searched per changed region (beyond
+ * that the diff stays valid, just not minimal), cut to `maxBytes` characters
+ * with a note when longer.
+ */
+export declare const unifiedDiff: (path: string, before: string, after: string, maxChars: number) => string;

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

@@ -0,0 +1,68 @@
+import { Option, Result, TextDiff } from "effect";
+const failure = (error, message) => ({ error, message });
+export const lineEndingOf = (text) => !text.includes("\r") ? "lf" : text.includes(`\r
+`) && !/(^|[^\r])\n/.test(text) ? "crlf" : "mixed", normalizeLine = (line) => line.normalize("NFKC").replace(/[\u2018\u2019\u201A\u201B\u2032\u2035]/g, "'").replace(/[\u201C\u201D\u201E\u201F\u2033\u2036]/g, '"').replace(/[\u2010-\u2015\u2212]/g, "-").replace(/\s+/g, " ").trim();
+const label = (index, count) => count === 1 ? "oldText" : `edit ${index + 1}'s oldText`, exactSpan = (base, edit, index, count) => {
+  const first = base.indexOf(edit.oldText);
+  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.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(`
+`), wantedLines = edit.oldText.split(`
+`), wanted = (withBreak ? wantedLines.slice(0, -1) : wantedLines).map(normalizeLine);
+  if (wanted.every((line) => line.length === 0))
+    return Result.succeed(Option.none());
+  const lines = base.split(`
+`), normal = lines.map(normalizeLine), starts = Array.from({ length: Math.max(0, lines.length - wanted.length + 1) }, (_, at) => at).filter((at) => wanted.every((line, offset) => normal[at + offset] === line)), [start, ...others] = starts;
+  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`));
+  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) => {
+  if (edit.oldText.length === 0)
+    return Result.fail(failure("EmptyOldText", `${label(index, count)} is empty; to create a file or replace all of it, use write`));
+  return Result.flatMap(exactSpan(base, edit, index, count), Option.match({
+    onSome: Result.succeed,
+    onNone: () => Result.flatMap(fuzzy ? normalizedSpan(base, edit, index, count) : Result.succeed(Option.none()), Option.match({
+      onSome: Result.succeed,
+      onNone: () => Result.fail(failure("NoMatch", `${label(index, count)} was not found in the file; read it again and copy the text exactly, whitespace included`))
+    }))
+  }));
+};
+export const applyTextEdits = (original, edits, options) => {
+  const ending = lineEndingOf(original), plain = (text) => ending === "mixed" ? text : text.replaceAll(`\r
+`, `
+`), base = plain(original), found = Result.all(edits.map((edit, index) => spanOf(base, { oldText: plain(edit.oldText), newText: plain(edit.newText) }, index, edits.length, options.fuzzy)));
+  return Result.flatMap(found, (spans) => {
+    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`));
+    }
+    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)
+      return Result.fail(failure("NoChange", "the edits leave the file as it is"));
+    const firstStart = ordered[0]?.start ?? 0;
+    return Result.succeed({
+      text: ending === "crlf" ? after.replaceAll(`
+`, `\r
+`) : after,
+      before: base,
+      after,
+      replaced: ordered.length,
+      normalized: ordered.some((span) => span.normalized),
+      firstChangedLine: base.slice(0, firstStart).split(`
+`).length
+    });
+  });
+}, unifiedDiff = (path, before, after, maxChars) => {
+  const diff = TextDiff.unified(TextDiff.lines(before, after, { maxEdits: 1e4 }), { fromFile: path, toFile: path });
+  return diff.length <= maxChars ? diff : `${diff.slice(0, maxChars)}
+[diff cut at ${maxChars} characters]
+`;
+};

package/dist/text-edit.entity.functions.test.d.ts

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

package/dist/text-edit.entity.js

@@ -0,0 +1,15 @@
+import { Schema } from "effect";
+export const LineEnding = Schema.Literals(["lf", "crlf", "mixed"]), EditPlan = Schema.Struct({
+  text: Schema.String,
+  before: Schema.String,
+  after: Schema.String,
+  replaced: Schema.Int,
+  normalized: Schema.Boolean,
+  firstChangedLine: Schema.Int
+}), EditSpan = Schema.Struct({
+  index: Schema.Int,
+  start: Schema.Int,
+  end: Schema.Int,
+  newText: Schema.String,
+  normalized: Schema.Boolean
+});