@xandreed/plugin-workspace 0.0.0-stage → 0.15.0

package/dist/ripgrep.adapter.js

@@ -0,0 +1,56 @@
+import { Effect, Option, Stream } from "effect";
+import { Bash, RunContext } from "@xandreed/core";
+import { rgReasonOf } from "./local-system.entity.functions.js";
+import { decodeRgMessage, emptyRgSearch, foldRgMessage, rgLines, rgRecords, ripgrepCommand } from "./ripgrep.entity.functions.js";
+import { clipHead } from "./text-window.entity.functions.js";
+import { displayOf, excludesBelow, isWithin } from "./workspace-path.entity.functions.js";
+import { bashEnvironment } from "./workspace-tools.entity.functions.js";
+const empty = { search: emptyRgSearch, buffer: "", stderr: "", exit: Option.none(), invalid: !1 }, failure = (error, message) => ({ error, message });
+export const searchRipgrep = Effect.fn("workspace.grep")(function* (access, target, directory, params, config) {
+  const bash = yield* Bash, run = yield* Effect.serviceOption(RunContext), cwd = directory ? target.path : access.path.dirname(target.path), input = directory ? "." : access.path.basename(target.path), exclude = excludesBelow(config.exclude, isWithin(access.root, cwd) ? Option.some(access.path.relative(access.root, cwd)) : Option.none()), limit = params.limit ?? config.grepMatches, perFile = directory ? Math.max(1, Math.ceil(limit / 4)) : limit, options = { limit, perFile, directory, lineChars: config.grepLineChars, display: (path) => displayOf(access, access.path.resolve(cwd, path)) }, fold = (state, event) => {
+    if (event._tag === "BashExit")
+      return { ...state, exit: Option.some(event) };
+    if (event.stream === "stderr")
+      return { ...state, stderr: clipHead(state.stderr + event.text, 16384) };
+    const complete = state.buffer + event.text;
+    if (complete.split(`
+`).some((line) => line.length > config.maxFileBytes * 6 + 65536))
+      return { ...state, invalid: !0 };
+    const parsed = rgRecords("", complete);
+    return { ...state, buffer: parsed.buffer, search: parsed.records.reduce((search, message) => search.stopped ? search : foldRgMessage(search, message, options), state.search) };
+  }, output = yield* bash.stream(ripgrepCommand(config, params, input, perFile, exclude), {
+    cwd,
+    stdin: params.pattern.length === 0 ? `
+` : params.pattern,
+    timeoutMs: config.grepTimeoutMs,
+    ...bashEnvironment(config, Option.map(run, (current) => ({ sessionId: String(current.session.id), runId: current.runId, workspace: access.root })))
+  }).pipe(Stream.mapAccum(() => empty, (state, event) => {
+    const next = fold(state, event);
+    return [next, [next]];
+  }), Stream.takeUntil((state) => state.search.stopped || state.invalid), Stream.runFold(() => empty, (_previous, state) => state), Effect.mapError((error) => failure(error.reason, error.message))), search = Option.match(decodeRgMessage(output.buffer), {
+    onNone: () => output.search,
+    onSome: (message) => foldRgMessage(output.search, message, options)
+  });
+  if (output.invalid)
+    return yield* Effect.fail(failure("SearchFailed", "The search output was too large to read; narrow the path or the pattern and search again"));
+  const timedOut = Option.exists(output.exit, (exit) => exit.termination === "timeout"), unreadable = output.stderr.split(`
+`).flatMap((line) => {
+    const found = /^rg: (.*): .*\(os error (\d+)\)$/.exec(line);
+    return found === null ? [] : [{ path: options.display(found[1] ?? ""), reason: rgReasonOf(Number(found[2])) }];
+  });
+  if (Option.exists(output.exit, (exit) => Option.contains(exit.exitCode, 2)) && search.messages === 0 && unreadable.length === 0)
+    return yield* Effect.fail(failure("InvalidPattern", `The search pattern or glob could not be parsed: ${output.stderr.trim()}. Pass literal: true to search for the pattern as text`));
+  if (Option.exists(output.exit, (exit) => exit.termination === "signal" || exit.termination === "exit" && !Option.exists(exit.exitCode, (code) => code === 0 || code === 1 || code === 2)))
+    return yield* Effect.fail(failure("SearchFailed", "The file search could not finish; try a narrower path or tell the user the search is unavailable"));
+  return {
+    pattern: params.pattern,
+    path: target.display,
+    lines: rgLines(search, params.context ?? 0),
+    matches: [...search.counts.values()].reduce((sum, count) => sum + count, 0),
+    files: search.counts.size,
+    skipped: search.skipped,
+    truncated: search.truncated,
+    unreadable,
+    timedOut
+  };
+});

package/dist/ripgrep.entity.d.ts

@@ -0,0 +1,63 @@
+import { Schema } from "effect";
+/** ripgrep represents non-UTF-8 paths and lines as base64 bytes. */
+export declare const RgText: Schema.Union<readonly [Schema.Struct<{
+    readonly text: Schema.String;
+}>, Schema.Struct<{
+    readonly bytes: Schema.StringFromBase64;
+}>]>;
+export type RgText = typeof RgText.Type;
+/** Only the fields the workspace search consumes from ripgrep's JSON stream. */
+export declare const RgMessage: Schema.toTaggedUnion<"type", readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"begin">;
+    readonly data: Schema.Struct<{
+        readonly path: Schema.Union<readonly [Schema.Struct<{
+            readonly text: Schema.String;
+        }>, Schema.Struct<{
+            readonly bytes: Schema.StringFromBase64;
+        }>]>;
+    }>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"match">;
+    readonly data: Schema.Struct<{
+        readonly path: Schema.Union<readonly [Schema.Struct<{
+            readonly text: Schema.String;
+        }>, Schema.Struct<{
+            readonly bytes: Schema.StringFromBase64;
+        }>]>;
+        readonly lines: Schema.Union<readonly [Schema.Struct<{
+            readonly text: Schema.String;
+        }>, Schema.Struct<{
+            readonly bytes: Schema.StringFromBase64;
+        }>]>;
+        readonly line_number: Schema.Int;
+    }>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"context">;
+    readonly data: Schema.Struct<{
+        readonly path: Schema.Union<readonly [Schema.Struct<{
+            readonly text: Schema.String;
+        }>, Schema.Struct<{
+            readonly bytes: Schema.StringFromBase64;
+        }>]>;
+        readonly lines: Schema.Union<readonly [Schema.Struct<{
+            readonly text: Schema.String;
+        }>, Schema.Struct<{
+            readonly bytes: Schema.StringFromBase64;
+        }>]>;
+        readonly line_number: Schema.Int;
+    }>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"end">;
+    readonly data: Schema.Struct<{
+        readonly path: Schema.Union<readonly [Schema.Struct<{
+            readonly text: Schema.String;
+        }>, Schema.Struct<{
+            readonly bytes: Schema.StringFromBase64;
+        }>]>;
+        readonly binary_offset: Schema.NullOr<Schema.Int>;
+    }>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"summary">;
+    readonly data: Schema.Struct<{}>;
+}>]>;
+export type RgMessage = typeof RgMessage.Type;

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

@@ -0,0 +1,68 @@
+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.
+ *
+ * @public
+ */
+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).
+ *
+ * @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

@@ -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), { 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.15.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.entity.d.ts

@@ -0,0 +1,99 @@
+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.brand<Schema.Trimmed, "SkillId">;
+                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.brand<Schema.Trimmed, "SkillReferenceId">;
+                    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.brand<Schema.Trimmed, "SkillId">;
+        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.brand<Schema.Trimmed, "SkillReferenceId">;
+            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.
+ *
+ * - `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`.
+ *
+ * @public
+ */
+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;
+/** @public */
+export declare const skillsDirectoryDefaults: SkillsDirectoryConfig;

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

@@ -0,0 +1,88 @@
+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.
+ *
+ * @public
+ */
+export declare const SKILLS_CAPABILITY_ID = "@xandreed/plugin-workspace/skills";
+/**
+ * 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`
+ * 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: {
+    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.
+ *
+ * @public
+ */
+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, 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: 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 = 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"})`), { 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;
+}), 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) => definePromptSection({
+    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.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
+};