@xandreed/core 0.12.0 → 0.14.0

package/dist/harness/skill-files.entity.d.ts

@@ -0,0 +1,101 @@
+import { Schema } from "effect";
+/**
+ * One file of a skills tree, as read: its path relative to the tree's root
+ * (POSIX, `/`-separated: `SKILL.md`, `git/SKILL.md`,
+ * `git/references/style.md`) and its text. `size` is set only for a file
+ * that was not read because it is too large (`collectSkillFiles`'
+ * `maxFileBytes`): its size in bytes, with an empty `text`;
+ * `readSkillFiles` leaves such a file out with a warning.
+ */
+export declare const SkillFile: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly text: Schema.String;
+    readonly size: Schema.optionalKey<Schema.Int>;
+}>;
+export type SkillFile = typeof SkillFile.Type;
+/**
+ * Something met while reading a skills tree, at a path relative to its root.
+ * An `error` leaves the skill out (its `SKILL.md` has no frontmatter or no
+ * description, its id is taken); a `warning` leaves out part of a skill (a
+ * reference over the size limit, or one whose path is not a valid id) or a
+ * value it could not read.
+ */
+export declare const SkillFileIssue: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly severity: Schema.Literals<readonly ["error", "warning"]>;
+    readonly message: Schema.String;
+}>;
+export type SkillFileIssue = typeof SkillFileIssue.Type;
+/** One skill of a tree: the directory its `SKILL.md` is in, relative to the tree's root (`""` for the root itself), and the skill. */
+export declare const SkillTreeEntry: 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;
+        }>>;
+    }>;
+}>;
+export type SkillTreeEntry = typeof SkillTreeEntry.Type;
+/** A directory tree of skills as read: every skill that loaded, by the path of its `SKILL.md`, and the issues met. */
+export declare const SkillTree: 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 SkillTree = typeof SkillTree.Type;
+/**
+ * How `readSkillFiles` reads a tree. `tools`: `"declared"` (the default)
+ * keeps each skill's `tools` field, `"ignore"` drops it, so loading a skill
+ * from the tree activates no tool. `maxReferenceBytes`: a reference larger
+ * than this (UTF-8 bytes) is left out with a warning; no limit when absent.
+ * `rootName`: the id of a `SKILL.md` at the tree's root that names none; a
+ * root `SKILL.md` without an id is an error when absent.
+ */
+export declare const SkillFilesOptions: Schema.Struct<{
+    readonly tools: Schema.optionalKey<Schema.Literals<readonly ["declared", "ignore"]>>;
+    readonly maxReferenceBytes: Schema.optionalKey<Schema.Int>;
+    readonly rootName: Schema.optionalKey<Schema.String>;
+}>;
+export type SkillFilesOptions = typeof SkillFilesOptions.Type;
+/**
+ * How much of a directory `collectSkillFiles` reads: at most `maxFiles`
+ * files and `maxBytes` bytes of text, or it fails with `skills.limit`.
+ * `maxFileBytes`: a file other than a `SKILL.md` larger than this is not
+ * read and does not count toward `maxBytes`; it is collected with its
+ * `size` (give `readSkillFiles` the same `maxReferenceBytes`). No limit when
+ * absent.
+ */
+export declare const CollectSkillFilesOptions: Schema.Struct<{
+    readonly maxFiles: Schema.Int;
+    readonly maxBytes: Schema.Int;
+    readonly maxFileBytes: Schema.optionalKey<Schema.Int>;
+}>;
+export type CollectSkillFilesOptions = typeof CollectSkillFilesOptions.Type;

package/dist/harness/skill-files.entity.functions.d.ts

@@ -0,0 +1,58 @@
+import { Effect } from "effect";
+import type { FsError } from "../domain/file-system.entity.js";
+import { FileSystem } from "../ports/file-system.port.js";
+import { SkillDefinition } from "./capability.entity.js";
+import { HarnessError } from "./plugin.entity.js";
+import type { CollectSkillFilesOptions, SkillFile, SkillFileIssue, SkillFilesOptions, SkillTree } from "./skill-files.entity.js";
+/**
+ * Skills from a tree of files (paths relative to the tree's root, as
+ * `collectSkillFiles` reads them). Never fails: what cannot be read is an
+ * issue, and the rest loads.
+ *
+ * - Every `SKILL.md`, at any depth, is a skill, and its directory is the
+ *   skill's. A file belongs to the deepest skill directory it is in; a
+ *   nested skill's files are its own, never its parent's. Files outside every
+ *   skill directory are not read.
+ * - A `SKILL.md` opens with `---` frontmatter (see the fields below); its
+ *   body is the skill's instructions (what `load_skill` returns).
+ * - Every other file of a skill is a reference (what `read_skill_reference`
+ *   serves), its id the path below the skill's directory
+ *   (`references/formats.md`, `scripts/check.sh`).
+ *
+ * Fields: `id` (else `name`, else the directory's path below the root, else
+ * for a `SKILL.md` at the root `options.rootName`), `summary` (else
+ * `description`; required; its whitespace and line ends collapsed to one
+ * line, the catalogue's), `version` (default: a fingerprint of the skill as
+ * read, its `SKILL.md` and the references it serves), `tools` and
+ * `permissions` (a list, or text split on commas and whitespace), `always`
+ * (`true` or `false`, any case). Other fields (`license`, `metadata`,
+ * `allowed-tools`, ...) are ignored. A second skill with an id already used
+ * is left out with an error; a reference that cannot be served (over
+ * `maxReferenceBytes`, not read, a path that is not a valid id) is left out
+ * with a warning.
+ */
+export declare const readSkillFiles: (files: ReadonlyArray<SkillFile>, options?: SkillFilesOptions) => SkillTree;
+/** Issues as one message: `<path>: <message>` each, in order. */
+export declare const skillIssuesText: (issues: ReadonlyArray<SkillFileIssue>) => string;
+/**
+ * `readSkillFiles`, strict: any issue, error or warning, fails with
+ * `skills.files` naming each one, so nothing is left out silently.
+ */
+export declare const skillsFromFiles: (files: ReadonlyArray<SkillFile>, options?: SkillFilesOptions) => Effect.Effect<ReadonlyArray<SkillDefinition>, HarnessError>;
+/**
+ * The text files under `root` (an absolute directory), as `readSkillFiles`
+ * takes them: paths relative to `root`, in `glob` order. The walk is the
+ * port's `glob("**\/*")`: links are not entered, entries whose name starts
+ * with a dot and `node_modules` directories are skipped. A binary file (a
+ * NUL byte or bytes that are not UTF-8) is left out and does not count
+ * toward `maxBytes`, told by its first 8 KB or, once read whole, by all of
+ * it; without `maxFileBytes`, one whose first sign of binary lies past what
+ * the budget has left fails it. A file other than a `SKILL.md` larger than
+ * `maxFileBytes` is not read: it is collected with its `size` and no text,
+ * and does not count toward `maxBytes` either.
+ * More than `maxFiles` files, or more than `maxBytes` bytes of text, fails
+ * with `skills.limit`. A file gone between the walk and its read is skipped;
+ * any other read failure, or a `root` that cannot be listed, is the
+ * `FsError`.
+ */
+export declare const collectSkillFiles: (root: string, options: CollectSkillFilesOptions) => Effect.Effect<ReadonlyArray<SkillFile>, FsError | HarnessError, FileSystem>;

package/dist/harness/skill-files.entity.functions.js

@@ -0,0 +1,150 @@
+import { Effect, Option, Result, Schema } from "effect";
+import { canonicalJson, fingerprintOf } from "../memory/memory-log.entity.functions.js";
+import { FileSystem } from "../ports/file-system.port.js";
+import { SkillDefinition, SkillReference } from "./capability.entity.js";
+import { HarnessError } from "./plugin.entity.js";
+const normalized = (text) => text.replace(/^\uFEFF/, "").replace(/\r\n?/g, `
+`), keyLine = /^([^\s#:\-][^:]*):[ \t]*(.*)$/, blockScalar = /^([|>])[+-]?[1-9]?[+-]?$/, isBlank = (line) => line.trim().length === 0, indentOf = (line) => line.length - line.trimStart().length, unquoted = (value) => {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"'))
+    return value.slice(1, -1).replace(/\\(["\\nt])/g, (_, escaped) => escaped === "n" ? `
+` : escaped === "t" ? "\t" : escaped);
+  return value.length >= 2 && value.startsWith("'") && value.endsWith("'") ? value.slice(1, -1).replaceAll("''", "'") : value;
+}, quoted = /^("(?:[^"\\]|\\.)*"|'(?:[^']|'')*')(.*)$/, withoutComment = (value) => {
+  if (!value.startsWith('"') && !value.startsWith("'"))
+    return value.replace(/(^|\s)#.*$/, "").trim();
+  const found = quoted.exec(value), after = (found?.[2] ?? "").trim();
+  return found !== null && (after.length === 0 || after.startsWith("#")) ? found[1] ?? value : value;
+}, dedented = (lines) => {
+  const indent = Math.min(...lines.filter((line) => !isBlank(line)).map(indentOf)), kept = lines.map((line) => isBlank(line) ? "" : line.slice(indent)), last = kept.findLastIndex((line) => line.length > 0);
+  return kept.slice(0, last + 1);
+}, blockText = (style, lines) => {
+  const content = dedented(lines);
+  if (style === "|")
+    return content.join(`
+`);
+  return content.reduce((paragraphs, line) => line.length === 0 ? [...paragraphs, []] : [...paragraphs.slice(0, -1), [...paragraphs.at(-1) ?? [], line.trim()]], [[]]).map((paragraph) => paragraph.join(" ")).join(`
+`).trim();
+}, textValue = (text) => ({ text: Option.some(text), items: Option.none() }), listValue = (items) => ({ text: Option.none(), items: Option.some(items) }), flowItems = (value) => value.slice(1, -1).split(",").map((item) => unquoted(item.trim())).filter((item) => item.length > 0), valueOf = (block) => {
+  const inline = withoutComment(block.inline), lines = block.rest.filter((line) => !isBlank(line)), style = blockScalar.exec(inline);
+  if (style !== null)
+    return textValue(blockText(style[1] ?? "|", block.rest));
+  if (inline.length === 0) {
+    if (lines.length > 0 && lines.every((line) => line.trim() === "-" || line.trim().startsWith("- ")))
+      return listValue(lines.map((line) => unquoted(withoutComment(line.trim().slice(1).trim()))).filter((item) => item.length > 0));
+    return lines.some((line) => keyLine.test(line.trim())) ? { text: Option.none(), items: Option.none() } : textValue(lines.map((line) => line.trim()).join(" "));
+  }
+  const whole = [inline, ...lines.map((line) => line.trim())].join(" ");
+  if (whole.startsWith("[") && whole.endsWith("]"))
+    return listValue(flowItems(whole));
+  return textValue(unquoted(whole));
+}, documentOf = (text) => {
+  const lines = normalized(text).split(`
+`);
+  if (lines[0]?.trimEnd() !== "---")
+    return Option.none();
+  const close = lines.findIndex((line, index) => index > 0 && line.trimEnd() === "---");
+  if (close < 0)
+    return Option.none();
+  const grouped = lines.slice(1, close).reduce((state, line, index) => {
+    const current = state.blocks.at(-1), attach = () => current === void 0 ? state : { ...state, blocks: [...state.blocks.slice(0, -1), { ...current, rest: [...current.rest, line] }] };
+    if (isBlank(line) || indentOf(line) > 0 || line.startsWith("- ") || line === "-")
+      return attach();
+    if (line.startsWith("#"))
+      return state;
+    const found = keyLine.exec(line);
+    if (found === null)
+      return { ...state, unread: [...state.unread, index + 2] };
+    return { ...state, blocks: [...state.blocks, { key: (found[1] ?? "").trim(), inline: (found[2] ?? "").trim(), rest: [] }] };
+  }, { blocks: [], unread: [] });
+  return Option.some({
+    fields: new Map(grouped.blocks.map((block) => [block.key, valueOf(block)])),
+    body: lines.slice(close + 1).join(`
+`),
+    unread: grouped.unread
+  });
+}, textField = (document, key) => Option.filter(Option.flatMap(Option.fromNullishOr(document.fields.get(key)), (value) => Option.map(value.text, (text) => text.trim())), (text) => text.length > 0), listField = (document, key) => Option.match(Option.fromNullishOr(document.fields.get(key)), {
+  onNone: () => [],
+  onSome: (value) => Option.getOrElse(Option.orElse(value.items, () => Option.map(value.text, (text) => text.split(/[\s,]+/))), () => []).map((item) => item.trim()).filter((item) => item.length > 0)
+}), skillFileName = "SKILL.md", encoder = new TextEncoder, segmentsOf = (path) => path.split("/").filter((segment) => segment.length > 0 && segment !== "."), directoryOf = (path) => segmentsOf(path).slice(0, -1).join("/"), isSkillFile = (path) => segmentsOf(path).at(-1) === skillFileName, within = (directory, path) => directory === "" || path.startsWith(`${directory}/`), relativeTo = (directory, path) => directory === "" ? path : path.slice(directory.length + 1), byPath = (left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0, issue = (path, severity, message) => ({ path, severity, message }), oneLine = (text) => text.replace(/\s+/g, " ").trim(), headingOf = (body) => Option.fromNullishOr(body.split(`
+`).filter((line) => line.startsWith("# ")).map((line) => line.slice(2).trim()).find((title) => title.length > 0)), referenceOf = (directory, file) => {
+  const id = relativeTo(directory, file.path), text = normalized(file.text), markdown = /\.(md|markdown)$/i.test(id), document = markdown ? documentOf(text) : Option.none(), body = Option.match(document, { onNone: () => text, onSome: (found) => found.body }), title = Option.orElse(Option.flatMap(document, (found) => textField(found, "title")), () => markdown ? headingOf(body) : Option.none());
+  return Result.mapError(Schema.decodeUnknownResult(SkillReference)({ id, title: oneLine(Option.getOrElse(title, () => id)), text: body.trim() }), (error) => issue(file.path, "warning", `left out: not a valid reference: ${oneLine(error.message)}`));
+}, ownedOf = (directory, file, limit) => {
+  const unread = Option.fromNullishOr(file.size), bytes = Option.getOrElse(unread, () => encoder.encode(file.text).length);
+  return Option.match(Option.filter(limit, (max) => bytes > max), {
+    onSome: (max) => Result.fail(issue(file.path, "warning", `left out: ${bytes} bytes, more than the ${max}-byte reference limit (maxReferenceBytes)`)),
+    onNone: () => Option.isSome(unread) ? Result.fail(issue(file.path, "warning", `left out: ${bytes} bytes, too large to be read (maxFileBytes)`)) : referenceOf(directory, file)
+  });
+}, skillOf = (skillFile, owned, options) => {
+  const directory = directoryOf(skillFile.path), failed = (message) => ({ entry: Option.none(), issues: [issue(skillFile.path, "error", message)] }), unread = Option.fromNullishOr(skillFile.size);
+  if (Option.isSome(unread))
+    return failed(`not read: ${unread.value} bytes, too large to be read (maxFileBytes)`);
+  return Option.match(documentOf(skillFile.text), {
+    onNone: () => failed("no frontmatter: a SKILL.md opens with a --- fence holding at least a description"),
+    onSome: (document) => {
+      const fallbackId = directory === "" ? Option.fromNullishOr(options.rootName) : Option.some(directory), id = Option.orElse(Option.orElse(textField(document, "id"), () => textField(document, "name")), () => fallbackId), summary = Option.orElse(textField(document, "summary"), () => textField(document, "description"));
+      if (Option.isNone(id))
+        return failed("a SKILL.md at the root names its skill: give it an id or a name");
+      if (Option.isNone(summary))
+        return failed("no description: the frontmatter needs a description (or summary)");
+      const always = textField(document, "always").pipe(Option.map((value) => value.toLowerCase())), parts = owned.map((file) => ownedOf(directory, file, Option.fromNullishOr(options.maxReferenceBytes))), references = parts.flatMap((part) => Option.toArray(Result.getSuccess(part))), warnings = [
+        ...document.unread.map((line) => issue(skillFile.path, "warning", `frontmatter line ${line} is not \`key: value\` and was not read`)),
+        ...Option.isSome(always) && always.value !== "true" && always.value !== "false" ? [issue(skillFile.path, "warning", `always is true or false, not "${always.value}"; read as false`)] : [],
+        ...parts.flatMap((part) => Option.toArray(Result.getFailure(part)))
+      ], read = {
+        id: id.value,
+        summary: oneLine(summary.value),
+        instructions: normalized(document.body).trim(),
+        tools: (options.tools ?? "declared") === "ignore" ? [] : listField(document, "tools"),
+        always: Option.contains(always, "true"),
+        permissions: listField(document, "permissions"),
+        references
+      }, version = Option.getOrElse(textField(document, "version"), () => fingerprintOf(canonicalJson(read)));
+      return Result.match(Schema.decodeUnknownResult(SkillDefinition)({ ...read, version }), {
+        onFailure: (error) => ({ entry: Option.none(), issues: [...warnings, issue(skillFile.path, "error", error.message)] }),
+        onSuccess: (skill) => ({ entry: Option.some({ directory, skill }), issues: warnings })
+      });
+    }
+  });
+};
+export const readSkillFiles = (files, options = {}) => {
+  const sorted = files.map((file) => ({ ...file, path: segmentsOf(file.path).join("/") })).toSorted(byPath), skillFiles = sorted.filter((file) => isSkillFile(file.path)), directories = skillFiles.map((file) => directoryOf(file.path)), ownerOf = (path) => Option.fromNullishOr(directories.filter((directory) => within(directory, path)).reduce((deepest, directory) => deepest === void 0 || directory.length > deepest.length ? directory : deepest, void 0)), owners = new Map(sorted.map((file) => [file, ownerOf(file.path)]));
+  return skillFiles.map((skillFile) => {
+    const directory = directoryOf(skillFile.path), owned = sorted.filter((file) => file !== skillFile && Option.contains(owners.get(file) ?? Option.none(), directory));
+    return { path: skillFile.path, ...skillOf(skillFile, owned, options) };
+  }).reduce((tree, { path, entry, issues }) => Option.match(entry, {
+    onNone: () => ({ ...tree, issues: [...tree.issues, ...issues] }),
+    onSome: (found) => {
+      const taken = tree.skills.find((other) => other.skill.id === found.skill.id);
+      return taken === void 0 ? { skills: [...tree.skills, found], issues: [...tree.issues, ...issues] } : { ...tree, issues: [...tree.issues, ...issues, issue(path, "error", `the skill id ${found.skill.id} is already used by ${taken.directory === "" ? "" : `${taken.directory}/`}${skillFileName}`)] };
+    }
+  }), { skills: [], issues: [] });
+}, skillIssuesText = (issues) => issues.map((found) => `${found.path}: ${found.message}`).join("; "), skillsFromFiles = (files, options = {}) => {
+  const tree = readSkillFiles(files, options);
+  return tree.issues.length > 0 ? Effect.fail(new HarnessError({ code: "skills.files", message: skillIssuesText(tree.issues) })) : Effect.succeed(tree.skills.map((entry) => entry.skill));
+};
+const probeBytes = 8192, limited = (message) => new HarnessError({ code: "skills.limit", message }), under = (root, path) => root.endsWith("/") ? `${root}${path}` : `${root}/${path}`, textOf = (bytes) => bytes.includes(0) ? Option.none() : Result.getSuccess(Result.try({ try: () => new TextDecoder("utf-8", { fatal: !0 }).decode(bytes), catch: () => "not UTF-8" })), beginsText = (bytes) => !bytes.includes(0) && Result.isSuccess(Result.try({ try: () => new TextDecoder("utf-8", { fatal: !0 }).decode(bytes, { stream: !0 }), catch: () => "not UTF-8" }));
+export const collectSkillFiles = (root, options) => Effect.gen(function* () {
+  const fs = yield* FileSystem, found = yield* fs.glob("**/*", { cwd: root, onlyFiles: !0, exclude: ["node_modules"], limit: options.maxFiles });
+  if (found.truncated)
+    return yield* Effect.fail(limited(`${root} holds more than ${options.maxFiles} files (maxFiles)`));
+  const overBudget = limited(`the text files under ${root} hold more than ${options.maxBytes} bytes (maxBytes)`);
+  return (yield* Effect.reduce(found.paths, () => ({ files: [], bytes: 0 }), (state, path) => {
+    const full = under(root, path), remaining = options.maxBytes - state.bytes, cap = isSkillFile(path) ? Option.none() : Option.fromNullishOr(options.maxFileBytes), unread = (size) => ({ ...state, files: [...state.files, { path, text: "", size }] }), add = (content, complete) => {
+      if (!complete)
+        return beginsText(content) ? Effect.fail(overBudget) : Effect.succeed(state);
+      return Option.match(textOf(content), {
+        onNone: () => Effect.succeed(state),
+        onSome: (text) => content.length > remaining ? Effect.fail(overBudget) : Effect.succeed({ files: [...state.files, { path, text }], bytes: state.bytes + content.length })
+      });
+    };
+    return fs.readBytes(full, { length: probeBytes }).pipe(Effect.flatMap((probe) => {
+      if (!beginsText(probe))
+        return Effect.succeed(state);
+      if (probe.length < probeBytes)
+        return Option.isSome(Option.filter(cap, (max) => probe.length > max)) ? Effect.succeed(unread(probe.length)) : add(probe, !0);
+      const asked = Option.getOrElse(cap, () => remaining) + 1;
+      return Effect.flatMap(fs.readBytes(full, { length: asked }), (bytes) => Option.isSome(Option.filter(cap, (max) => bytes.length > max)) ? Effect.map(fs.stat(full), (info) => unread(info.size)) : add(bytes, bytes.length < asked));
+    }), Effect.catchTag("FsError", (error) => error.reason === "NotFound" ? Effect.succeed(state) : Effect.fail(error)));
+  })).files;
+});

package/dist/harness/skill-files.entity.functions.test.d.ts

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

package/dist/harness/skill-files.entity.js

@@ -0,0 +1,25 @@
+import { Schema } from "effect";
+import { SkillDefinition } from "./capability.entity.js";
+export const SkillFile = Schema.Struct({
+  path: Schema.String,
+  text: Schema.String,
+  size: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
+}), SkillFileIssue = Schema.Struct({
+  path: Schema.String,
+  severity: Schema.Literals(["error", "warning"]),
+  message: Schema.String
+}), SkillTreeEntry = Schema.Struct({
+  directory: Schema.String,
+  skill: SkillDefinition
+}), SkillTree = Schema.Struct({
+  skills: Schema.Array(SkillTreeEntry),
+  issues: Schema.Array(SkillFileIssue)
+}), SkillFilesOptions = Schema.Struct({
+  tools: Schema.optionalKey(Schema.Literals(["declared", "ignore"])),
+  maxReferenceBytes: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
+  rootName: Schema.optionalKey(Schema.String)
+}), CollectSkillFilesOptions = Schema.Struct({
+  maxFiles: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+  maxBytes: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+  maxFileBytes: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
+});

package/dist/index.d.ts

@@ -1,11 +1,14 @@
-export { AgentMessage, AgentResult, AssistantMessage, Checkpoint, ConversationId, ReasoningPart, TextPart, ToolCallId, ToolCallPart, ToolMessage, ToolResultPart, UserRoleMessage, } from "./domain/message.entity.js";
+export { AgentMessage, AgentResult, AssistantMessage, Checkpoint, ConversationId, ReasoningPart, TextPart, ToolCallId, ToolCallPart, ToolMessage, ToolResultPart, UserContentPart, UserRoleMessage, } from "./domain/message.entity.js";
+export { AttachmentRejected, AttachmentRejectedReason, ImageMediaType, Media, MEDIA_LIMITS, MediaFingerprint, MediaSlot, } from "./domain/media.entity.js";
+export { base64Length, elideMediaData, IMAGE_TOKEN_ESTIMATE, imageSizeOf, isMediaValue, mediaAt, mediaFingerprintOf, mediaFromBase64, mediaFromBytes, mediaLabel, mediaSlotsOf, normalizeMedia, sniffImageType, toolResultMedia, } from "./domain/media.entity.functions.js";
+export type { ImageSize, MediaDescription, ToolResultMedia } from "./domain/media.entity.functions.js";
 export { Failure } from "./domain/failure.entity.js";
 export { toFailure } from "./domain/failure.entity.functions.js";
 export { AgentFailure, AgentFailureCategory } from "./domain/agent-failure.entity.js";
 export type { AgentFailure as AgentFailureType, AgentFailureCategory as AgentFailureCategoryType } from "./domain/agent-failure.entity.js";
 export { toAgentFailure, toolResultFailure } from "./domain/agent-failure.entity.functions.js";
-export { TokenUsage } from "./domain/token-usage.entity.js";
-export { addUsage, zeroUsage } from "./domain/token-usage.entity.functions.js";
+export { BudgetTokens, ModelPrice, TokenUsage, UsageBreakdown } from "./domain/token-usage.entity.js";
+export { addUsage, costOf, isBudgetTokens, sumUsage, tokenUsage, uncachedInputTokens, usageBreakdown, zeroUsage, } from "./domain/token-usage.entity.functions.js";
 export { ModelId, ModelSelection, ProviderId, } from "./domain/model-selection.entity.js";
 export { ModelCallPolicy, ReasoningEffort } from "./domain/model-call-policy.entity.js";
 export type { ReasoningEffort as ReasoningEffortType } from "./domain/model-call-policy.entity.js";
@@ -15,18 +18,30 @@ export type { ModelCallPolicy as ModelCallPolicyType } from "./domain/model-call
 export { CurrentEmptyResponseTolerance, CurrentModelCallPolicy } from "./loop/modelPolicy.js";
 export { formatModelSelection, parseModelSelection } from "./domain/model-selection.entity.functions.js";
 export type { LoopEvent, ToolCallSummary } from "./domain/loop-event.entity.js";
-export { ConversationStore, ConversationSummary, RunOutcomeRecord, StoredMessage, StoreError, } from "./ports/conversation-store.port.js";
+export { DirEntry, FileInfo, FileKind, FsError, FsReason, GlobOptions, GlobResult, ReadRange, RecursiveOptions, StatOptions, WriteOptions } from "./domain/file-system.entity.js";
+export { walkGlob } from "./domain/file-system.entity.functions.js";
+export { BASH_ENV_ALLOWLIST, BashChunk, BashError, BashErrorReason, BashEvent, BashExit, BashOptions, BashResult, BashTermination } from "./domain/bash.entity.js";
+export { collectBashResult, resolveBashEnv } from "./domain/bash.entity.functions.js";
 export { EngineSettings, SETTINGS_KEYS, SettingsError, SettingsStore, } from "./ports/settings-store.port.js";
 export type { ModelRole, SettingsKey } from "./ports/settings-store.port.js";
 export { AuthError, AuthStore, Credential } from "./ports/auth-store.port.js";
 export { ModelCatalog } from "./ports/model-catalog.port.js";
-export { FileSystem, FsError } from "./ports/file-system.port.js";
-export { Shell, ShellError, ShellResult } from "./ports/shell.port.js";
+export { FileSystem } from "./ports/file-system.port.js";
+export { Bash } from "./ports/bash.port.js";
 export { UtilityCompletion, UtilityError, UtilityLlm } from "./ports/utility-llm.port.js";
 export { asJsonRecord, decodeJsonLines, parseJsonOption, parseJsonWarn } from "./util/json.js";
+export { compileGlob, globMatcher } from "./util/glob.js";
+export type { GlobMatcher, GlobMatchOptions } from "./util/glob.js";
+export { FileSystemMemoryLive, makeMemoryFileSystem } from "./workspace/file-system.memory.adapter.js";
+export type { MemoryFileSystem, MemorySeed } from "./workspace/file-system.memory.adapter.js";
+export { fileSystemConformance } from "./workspace/file-system.conformance.js";
+export type { FileSystemFixture, FileSystemSubject } from "./workspace/file-system.conformance.js";
+export { bashConformance } from "./workspace/bash.conformance.js";
+export type { BashFixture, BashSubject } from "./workspace/bash.conformance.js";
 export { assistantModel, assistantUsage, extractUsage, extractModel, handoffToMessage, safeKeepFrom, responseReasoning, responseText, responseToAgentMessages, responseToolCalls, responseToolResults, toPromptMessages, withToolCallIds, withUsageOnAssistant, } from "./loop/mapping.js";
 export type { ToolResultSummary } from "./loop/mapping.js";
 export { CurrentPromptCacheKey } from "./loop/cacheKey.js";
+export { CurrentTraceContent, replayableContext } from "./loop/traceContent.js";
 export { foldStreamParts } from "./loop/streamFold.js";
 export { strictJsonSchema, toolParametersSchema } from "./loop/toolSchema.js";
 export type { FoldedTurn, StreamDelta } from "./loop/streamFold.js";
@@ -39,14 +54,27 @@ export * from "./session/session-log.entity.js";
 export * from "./ports/session-log.port.js";
 export { SessionLogMemoryLive } from "./session/session-log.memory.adapter.js";
 export { sessionLogConformance } from "./session/session-log.conformance.js";
+export { sessionLogRecoveryConformance } from "./session/session-log.recovery.conformance.js";
+export type { SessionLogSubject } from "./session/session-log.recovery.conformance.js";
 export * from "./session/session-event.entity.js";
+export { JOURNAL_KINDS } from "./session/session-event.entity.js";
 export * from "./session/session-event.entity.functions.js";
+export { turnUsageOf } from "./session/session-event.entity.functions.js";
 export * from "./session/sessions.entity.js";
+export { resumeRefusal, turnEndingOf } from "./session/sessions.entity.functions.js";
+export type { ResumableTurn } from "./session/sessions.entity.functions.js";
 export * from "./ports/sessions.port.js";
 export * from "./ports/turn-admission.port.js";
 export { TurnAdmissionOpen } from "./session/turn-admission.open.adapter.js";
 export * from "./session/tasks.entity.js";
 export * from "./ports/tasks.port.js";
+export { ActiveTurn, ProcessActivity, TurnsInFlight } from "./session/activity.entity.js";
+export { awaitIdle, processActivity } from "./session/activity.entity.functions.js";
+export { TaskActivity, TurnActivity } from "./ports/activity.port.js";
+export { sessionsConformance } from "./session/sessions.conformance.js";
+export type { SessionsInstance, SessionsProcess, SessionsSubject } from "./session/sessions.conformance.js";
+export { taskRunnerConformance, tasksConformance } from "./session/tasks.conformance.js";
+export type { TaskRunnerFixture, TasksDependencies, TasksFixture } from "./session/tasks.conformance.js";
 export { DEFAULT_SPEC_LIMITS, renderSpecSection, SpecCheck, SpecDoc, SpecGates, SpecLimits, SpecSlug, SpecStatus, } from "./spec/SpecDoc.js";
 export { decodeSpecDocText, encodeSpecDocText, SpecDocParseError, specSlug, uniqueSlug, } from "./spec/codec.js";
 export { parseFrontmatter } from "./spec/frontmatter.js";
@@ -54,12 +82,12 @@ export * from "./harness/plugin.entity.js";
 export * from "./harness/plugin.adapter.js";
 export * from "./harness/plugin-stack.adapter.js";
 export * from "./harness/config.entity.js";
-export * from "./harness/session.entity.js";
 export * from "./ports/harness.port.js";
 export { defineAgent, defineConfig } from "./harness/config.entity.functions.js";
 export * from "./domain/prompt-provenance.entity.js";
 export * from "./loop/promptProvenance.js";
-export { CurrentAgentStep } from "./loop/stepContext.js";
+export { CurrentAgentStep, CurrentToolInvocation } from "./loop/stepContext.js";
+export type { ToolInvocation } from "./loop/stepContext.js";
 export * from "./decision-record.entity.js";
 export * from "./memory/memory-log.entity.js";
 export * from "./memory/memory-log.entity.functions.js";
@@ -72,7 +100,9 @@ export * from "./ports/permission.port.js";
 export * from "./ports/run-context.port.js";
 export * from "./ports/tool-registry.port.js";
 export * from "./turn/user-message.entity.js";
+export { attachmentsOf, normalizeUserMessage, sameUserMessage, userMessageText } from "./turn/user-message.entity.functions.js";
 export * from "./turn/turn-event.entity.js";
+export { StreamFallbackEvent, ToolRefusalReason, ToolRefusedEvent, TURN_EVENT_NAMES } from "./turn/turn-event.entity.js";
 export * from "./turn/turn-event.entity.functions.js";
 export * from "./turn/model-request.entity.js";
 export * from "./turn/model-request.entity.functions.js";
@@ -80,16 +110,24 @@ export * from "./turn/turn-bus.js";
 export * from "./ports/turn-events.port.js";
 export * from "./ports/step-loop.port.js";
 export * from "./ports/turn.port.js";
+export type { TurnResult } from "./ports/turn.port.js";
 export * from "./ports/turn-scope.port.js";
 export * from "./turn/prompt-sections.js";
 export * from "./turn/turn.adapter.js";
 export * from "./turn/turn-run.js";
 export * from "./turn/turn-lifecycle.js";
+export { traceTurn } from "./turn/turn-lifecycle.js";
+export type { TurnTraceOptions } from "./turn/turn-lifecycle.js";
 export * from "./decision-record.entity.functions.js";
-export { skillsFromFiles } from "./harness/skill-files.js";
-export type { SkillFile } from "./harness/skill-files.js";
+export { CollectSkillFilesOptions, SkillFile, SkillFileIssue, SkillFilesOptions, SkillTree, SkillTreeEntry } from "./harness/skill-files.entity.js";
+export { collectSkillFiles, readSkillFiles, skillIssuesText, skillsFromFiles } from "./harness/skill-files.entity.functions.js";
 export { ConformanceFailure } from "./conformance.entity.js";
 export type { ConformanceCheck } from "./conformance.entity.js";
 export { probeCall, stepLoopConformance, textReply } from "./turn/step-loop.conformance.js";
 export { inMemoryLog, memoryConformance } from "./memory/memory.conformance.js";
 export { turnConformance } from "./turn/turn.conformance.js";
+export { toolRegistryConformance } from "./turn/tool-registry.conformance.js";
+export type { ToolRegistryLimits } from "./turn/tool-registry.conformance.js";
+export { authStoreConformance } from "./models/auth-store.conformance.js";
+export { settingsStoreConformance } from "./models/settings-store.conformance.js";
+export { modelCatalogConformance } from "./models/model-catalog.conformance.js";

package/dist/index.js

@@ -10,14 +10,49 @@ export {
   ToolCallPart,
   ToolMessage,
   ToolResultPart,
+  UserContentPart,
   UserRoleMessage
 } from "./domain/message.entity.js";
+export {
+  AttachmentRejected,
+  AttachmentRejectedReason,
+  ImageMediaType,
+  Media,
+  MEDIA_LIMITS,
+  MediaFingerprint,
+  MediaSlot
+} from "./domain/media.entity.js";
+export {
+  base64Length,
+  elideMediaData,
+  IMAGE_TOKEN_ESTIMATE,
+  imageSizeOf,
+  isMediaValue,
+  mediaAt,
+  mediaFingerprintOf,
+  mediaFromBase64,
+  mediaFromBytes,
+  mediaLabel,
+  mediaSlotsOf,
+  normalizeMedia,
+  sniffImageType,
+  toolResultMedia
+} from "./domain/media.entity.functions.js";
 export { Failure } from "./domain/failure.entity.js";
 export { toFailure } from "./domain/failure.entity.functions.js";
 export { AgentFailure, AgentFailureCategory } from "./domain/agent-failure.entity.js";
 export { toAgentFailure, toolResultFailure } from "./domain/agent-failure.entity.functions.js";
-export { TokenUsage } from "./domain/token-usage.entity.js";
-export { addUsage, zeroUsage } from "./domain/token-usage.entity.functions.js";
+export { BudgetTokens, ModelPrice, TokenUsage, UsageBreakdown } from "./domain/token-usage.entity.js";
+export {
+  addUsage,
+  costOf,
+  isBudgetTokens,
+  sumUsage,
+  tokenUsage,
+  uncachedInputTokens,
+  usageBreakdown,
+  zeroUsage
+} from "./domain/token-usage.entity.functions.js";
 export {
   ModelId,
   ModelSelection,
@@ -27,13 +62,10 @@ export { ModelCallPolicy, ReasoningEffort } from "./domain/model-call-policy.ent
 export { ModelCatalogEntry } from "./domain/model-catalog.entity.js";
 export { CurrentEmptyResponseTolerance, CurrentModelCallPolicy } from "./loop/modelPolicy.js";
 export { formatModelSelection, parseModelSelection } from "./domain/model-selection.entity.functions.js";
-export {
-  ConversationStore,
-  ConversationSummary,
-  RunOutcomeRecord,
-  StoredMessage,
-  StoreError
-} from "./ports/conversation-store.port.js";
+export { DirEntry, FileInfo, FileKind, FsError, FsReason, GlobOptions, GlobResult, ReadRange, RecursiveOptions, StatOptions, WriteOptions } from "./domain/file-system.entity.js";
+export { walkGlob } from "./domain/file-system.entity.functions.js";
+export { BASH_ENV_ALLOWLIST, BashChunk, BashError, BashErrorReason, BashEvent, BashExit, BashOptions, BashResult, BashTermination } from "./domain/bash.entity.js";
+export { collectBashResult, resolveBashEnv } from "./domain/bash.entity.functions.js";
 export {
   EngineSettings,
   SETTINGS_KEYS,
@@ -42,10 +74,14 @@ export {
 } from "./ports/settings-store.port.js";
 export { AuthError, AuthStore, Credential } from "./ports/auth-store.port.js";
 export { ModelCatalog } from "./ports/model-catalog.port.js";
-export { FileSystem, FsError } from "./ports/file-system.port.js";
-export { Shell, ShellError, ShellResult } from "./ports/shell.port.js";
+export { FileSystem } from "./ports/file-system.port.js";
+export { Bash } from "./ports/bash.port.js";
 export { UtilityCompletion, UtilityError, UtilityLlm } from "./ports/utility-llm.port.js";
 export { asJsonRecord, decodeJsonLines, parseJsonOption, parseJsonWarn } from "./util/json.js";
+export { compileGlob, globMatcher } from "./util/glob.js";
+export { FileSystemMemoryLive, makeMemoryFileSystem } from "./workspace/file-system.memory.adapter.js";
+export { fileSystemConformance } from "./workspace/file-system.conformance.js";
+export { bashConformance } from "./workspace/bash.conformance.js";
 export {
   assistantModel,
   assistantUsage,
@@ -63,6 +99,7 @@ export {
   withUsageOnAssistant
 } from "./loop/mapping.js";
 export { CurrentPromptCacheKey } from "./loop/cacheKey.js";
+export { CurrentTraceContent, replayableContext } from "./loop/traceContent.js";
 export { foldStreamParts } from "./loop/streamFold.js";
 export { strictJsonSchema, toolParametersSchema } from "./loop/toolSchema.js";
 export { McpCallOutcome, McpClient, McpError, McpToolDescriptor } from "./ports/mcp-client.port.js";
@@ -72,14 +109,23 @@ export * from "./session/session-log.entity.js";
 export * from "./ports/session-log.port.js";
 export { SessionLogMemoryLive } from "./session/session-log.memory.adapter.js";
 export { sessionLogConformance } from "./session/session-log.conformance.js";
+export { sessionLogRecoveryConformance } from "./session/session-log.recovery.conformance.js";
 export * from "./session/session-event.entity.js";
+export { JOURNAL_KINDS } from "./session/session-event.entity.js";
 export * from "./session/session-event.entity.functions.js";
+export { turnUsageOf } from "./session/session-event.entity.functions.js";
 export * from "./session/sessions.entity.js";
+export { resumeRefusal, turnEndingOf } from "./session/sessions.entity.functions.js";
 export * from "./ports/sessions.port.js";
 export * from "./ports/turn-admission.port.js";
 export { TurnAdmissionOpen } from "./session/turn-admission.open.adapter.js";
 export * from "./session/tasks.entity.js";
 export * from "./ports/tasks.port.js";
+export { ActiveTurn, ProcessActivity, TurnsInFlight } from "./session/activity.entity.js";
+export { awaitIdle, processActivity } from "./session/activity.entity.functions.js";
+export { TaskActivity, TurnActivity } from "./ports/activity.port.js";
+export { sessionsConformance } from "./session/sessions.conformance.js";
+export { taskRunnerConformance, tasksConformance } from "./session/tasks.conformance.js";
 export {
   DEFAULT_SPEC_LIMITS,
   renderSpecSection,
@@ -102,12 +148,11 @@ export * from "./harness/plugin.entity.js";
 export * from "./harness/plugin.adapter.js";
 export * from "./harness/plugin-stack.adapter.js";
 export * from "./harness/config.entity.js";
-export * from "./harness/session.entity.js";
 export * from "./ports/harness.port.js";
 export { defineAgent, defineConfig } from "./harness/config.entity.functions.js";
 export * from "./domain/prompt-provenance.entity.js";
 export * from "./loop/promptProvenance.js";
-export { CurrentAgentStep } from "./loop/stepContext.js";
+export { CurrentAgentStep, CurrentToolInvocation } from "./loop/stepContext.js";
 export * from "./decision-record.entity.js";
 export * from "./memory/memory-log.entity.js";
 export * from "./memory/memory-log.entity.functions.js";
@@ -120,7 +165,9 @@ export * from "./ports/permission.port.js";
 export * from "./ports/run-context.port.js";
 export * from "./ports/tool-registry.port.js";
 export * from "./turn/user-message.entity.js";
+export { attachmentsOf, normalizeUserMessage, sameUserMessage, userMessageText } from "./turn/user-message.entity.functions.js";
 export * from "./turn/turn-event.entity.js";
+export { StreamFallbackEvent, ToolRefusalReason, ToolRefusedEvent, TURN_EVENT_NAMES } from "./turn/turn-event.entity.js";
 export * from "./turn/turn-event.entity.functions.js";
 export * from "./turn/model-request.entity.js";
 export * from "./turn/model-request.entity.functions.js";
@@ -133,9 +180,15 @@ export * from "./turn/prompt-sections.js";
 export * from "./turn/turn.adapter.js";
 export * from "./turn/turn-run.js";
 export * from "./turn/turn-lifecycle.js";
+export { traceTurn } from "./turn/turn-lifecycle.js";
 export * from "./decision-record.entity.functions.js";
-export { skillsFromFiles } from "./harness/skill-files.js";
+export { CollectSkillFilesOptions, SkillFile, SkillFileIssue, SkillFilesOptions, SkillTree, SkillTreeEntry } from "./harness/skill-files.entity.js";
+export { collectSkillFiles, readSkillFiles, skillIssuesText, skillsFromFiles } from "./harness/skill-files.entity.functions.js";
 export { ConformanceFailure } from "./conformance.entity.js";
 export { probeCall, stepLoopConformance, textReply } from "./turn/step-loop.conformance.js";
 export { inMemoryLog, memoryConformance } from "./memory/memory.conformance.js";
 export { turnConformance } from "./turn/turn.conformance.js";
+export { toolRegistryConformance } from "./turn/tool-registry.conformance.js";
+export { authStoreConformance } from "./models/auth-store.conformance.js";
+export { settingsStoreConformance } from "./models/settings-store.conformance.js";
+export { modelCatalogConformance } from "./models/model-catalog.conformance.js";