@batonfx/skills 0.4.0 → 0.4.2

package/README.md

@@ -0,0 +1,5 @@
+# `@batonfx/skills`
+
+Filesystem and hosted skill sources for Baton agents.
+
+See the [Baton documentation](https://github.com/In-Time-Tec/batonfx#readme) for installation, examples, and API guidance.

package/dist/github-catalog.d.ts

@@ -0,0 +1,18 @@
+import { Crypto } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { SkillSource } from "@batonfx/core";
+import { type Limits } from "./hosted-catalog.js";
+/** @experimental Manifest-backed GitHub catalog options. */
+export interface Options extends Limits {
+    readonly owner: string;
+    readonly repo: string;
+    readonly ref: string;
+    readonly root?: string;
+    readonly manifestName?: string;
+    readonly apiBaseUrl?: string;
+    readonly source?: string;
+}
+/** @experimental Build a manifest-backed immutable GitHub catalog source. */
+export declare const make: (options: Options) => SkillSource.Source<HttpClient.HttpClient | Crypto.Crypto>;
+/** @experimental Build a manifest-backed immutable GitHub catalog layer. */
+export declare const layer: (options: Options) => import("effect/Layer").Layer<SkillSource.SkillSource, SkillSource.SkillSourceError, HttpClient.HttpClient | Crypto.Crypto>;

package/dist/github-catalog.js

@@ -0,0 +1,53 @@
+import { Crypto, Effect } from "effect";
+import { HttpClient, Url } from "effect/unstable/http";
+import { SkillSource } from "@batonfx/core";
+import { make as makeHostedCatalog, validateSkillPath } from "./hosted-catalog.js";
+const encodedPath = (value) => value
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(encodeURIComponent)
+    .join("/");
+/** @experimental Build a manifest-backed immutable GitHub catalog source. */
+export const make = (options) => {
+    const source = options.source ?? `github:${options.owner}/${options.repo}@${options.ref}`;
+    if (!/^[0-9a-fA-F]{40}$|^[0-9a-fA-F]{64}$/.test(options.ref)) {
+        return Effect.fail(new SkillSource.SkillSourceError({ source, message: "GitHub skill catalog ref must be a commit id" }));
+    }
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/.test(options.owner) ||
+        !/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,98}[A-Za-z0-9])?$/.test(options.repo)) {
+        return Effect.fail(new SkillSource.SkillSourceError({ source, message: "Invalid GitHub owner or repository" }));
+    }
+    return Effect.gen(function* () {
+        if ((options.root?.length ?? 0) > 0)
+            yield* validateSkillPath(source, options.root ?? "");
+        yield* validateSkillPath(source, options.manifestName ?? "skills.json");
+        const apiBase = yield* Effect.fromResult(Url.fromString(options.apiBaseUrl ?? "https://api.github.com")).pipe(Effect.mapError((cause) => new SkillSource.SkillSourceError({ source, message: "Invalid GitHub API base URL", cause })));
+        if (apiBase.protocol !== "https:" ||
+            apiBase.username.length > 0 ||
+            apiBase.password.length > 0 ||
+            apiBase.search.length > 0 ||
+            apiBase.hash.length > 0) {
+            return yield* Effect.fail(new SkillSource.SkillSourceError({ source, message: "Invalid GitHub API base URL" }));
+        }
+        const base = apiBase.toString().replace(/\/$/, "");
+        const root = encodedPath(options.root ?? "");
+        const manifestName = encodedPath(options.manifestName ?? "skills.json");
+        const repository = `${base}/repos/${encodeURIComponent(options.owner)}/${encodeURIComponent(options.repo)}/contents`;
+        const rootUrl = `${repository}/${root.length === 0 ? "" : `${root}/`}`;
+        const manifestUrl = `${rootUrl}${manifestName}?ref=${encodeURIComponent(options.ref)}`;
+        const headers = {
+            accept: "application/vnd.github.raw+json",
+            "x-github-api-version": "2022-11-28",
+        };
+        return yield* makeHostedCatalog({
+            ...options,
+            source,
+            manifestUrl,
+            manifestHeaders: headers,
+            bodyHeaders: headers,
+            resolveSkillUrl: (skillPath) => validateSkillPath(source, skillPath).pipe(Effect.map((safePath) => `${rootUrl}${encodedPath(safePath)}?ref=${encodeURIComponent(options.ref)}`)),
+        });
+    });
+};
+/** @experimental Build a manifest-backed immutable GitHub catalog layer. */
+export const layer = (options) => SkillSource.layer([make(options)]);

package/dist/hosted-catalog.d.ts

@@ -0,0 +1,64 @@
+import { Crypto, Effect, Layer, Schema } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { SkillSource } from "@batonfx/core";
+/** @experimental Baton hosted skill manifest entry. */
+export declare const ManifestSkill: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.String;
+    readonly skillPath: Schema.String;
+    readonly sha256: Schema.String;
+    readonly whenToUse: Schema.optionalKey<Schema.String>;
+    readonly allowedTools: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly disableModelInvocation: Schema.optionalKey<Schema.Boolean>;
+    readonly userInvocable: Schema.optionalKey<Schema.Boolean>;
+    readonly contextFork: Schema.optionalKey<Schema.Boolean>;
+    readonly agent: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+    readonly paths: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>;
+/** @experimental */
+export type ManifestSkill = typeof ManifestSkill.Type;
+/** @experimental Baton hosted skill manifest. */
+export declare const Manifest: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly skills: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly description: Schema.String;
+        readonly skillPath: Schema.String;
+        readonly sha256: Schema.String;
+        readonly whenToUse: Schema.optionalKey<Schema.String>;
+        readonly allowedTools: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly disableModelInvocation: Schema.optionalKey<Schema.Boolean>;
+        readonly userInvocable: Schema.optionalKey<Schema.Boolean>;
+        readonly contextFork: Schema.optionalKey<Schema.Boolean>;
+        readonly agent: Schema.optionalKey<Schema.String>;
+        readonly model: Schema.optionalKey<Schema.String>;
+        readonly paths: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
+}>;
+/** @experimental */
+export type Manifest = typeof Manifest.Type;
+/** @experimental Shared hosted-catalog limits and trusted tools. */
+export interface Limits {
+    readonly manifestMaxBytes?: number;
+    readonly bodyMaxBytes?: number;
+    readonly maxSkills?: number;
+    readonly descriptionCap?: number;
+    readonly toolsBySkill?: Readonly<Record<string, ReadonlyArray<SkillSource.Skill["tools"][number]>>>;
+}
+/** @experimental Internal hosted-catalog construction options. */
+export interface MakeOptions extends Limits {
+    readonly source: string;
+    readonly manifestUrl: string;
+    readonly resolveSkillUrl: (skillPath: string) => Effect.Effect<string, SkillSource.SkillSourceError>;
+    readonly manifestHeaders?: Readonly<Record<string, string>>;
+    readonly bodyHeaders?: Readonly<Record<string, string>>;
+}
+/** @experimental Validate one safe relative SKILL.md path. */
+export declare const validateSkillPath: (source: string, skillPath: string) => Effect.Effect<string, SkillSource.SkillSourceError>;
+/** @experimental Resolve a same-origin path beneath a manifest directory. */
+export declare const resolveRelative: (source: string, manifestUrl: string, skillPath: string) => Effect.Effect<string, SkillSource.SkillSourceError>;
+/** @experimental Build a hosted manifest source over Effect HTTP and Crypto services. */
+export declare const make: (options: MakeOptions) => SkillSource.Source<HttpClient.HttpClient | Crypto.Crypto>;
+/** @experimental One-source hosted catalog layer. */
+export declare const layer: (options: MakeOptions) => Layer.Layer<SkillSource.SkillSource, SkillSource.SkillSourceError, HttpClient.HttpClient | Crypto.Crypto>;

package/dist/hosted-catalog.js

@@ -0,0 +1,147 @@
+import { Crypto, Effect, Encoding, Layer, Schema, Stream } from "effect";
+import { HttpClient, HttpClientRequest, HttpClientResponse, Url } from "effect/unstable/http";
+import { SkillSource } from "@batonfx/core";
+import { parseDocument, validateName } from "./skill-document.js";
+/** @experimental Baton hosted skill manifest entry. */
+export const ManifestSkill = Schema.Struct({
+    name: Schema.String,
+    description: Schema.String,
+    skillPath: Schema.String,
+    sha256: Schema.String,
+    whenToUse: Schema.optionalKey(Schema.String),
+    allowedTools: Schema.optionalKey(Schema.Array(Schema.String)),
+    disableModelInvocation: Schema.optionalKey(Schema.Boolean),
+    userInvocable: Schema.optionalKey(Schema.Boolean),
+    contextFork: Schema.optionalKey(Schema.Boolean),
+    agent: Schema.optionalKey(Schema.String),
+    model: Schema.optionalKey(Schema.String),
+    paths: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+/** @experimental Baton hosted skill manifest. */
+export const Manifest = Schema.Struct({
+    version: Schema.Literal(1),
+    skills: Schema.Array(ManifestSkill),
+});
+const decoder = new TextDecoder("utf-8", { fatal: true });
+const sourceError = (source, message, cause) => new SkillSource.SkillSourceError({ source, message, ...(cause === undefined ? {} : { cause }) });
+const safeInteger = (source, name, value, minimum) => Number.isSafeInteger(value) && value >= minimum
+    ? Effect.succeed(value)
+    : Effect.fail(sourceError(source, `${name} must be a safe integer >= ${minimum}`));
+const request = (url, headers) => {
+    let value = HttpClientRequest.get(url);
+    for (const [name, header] of Object.entries(headers ?? {}))
+        value = HttpClientRequest.setHeader(value, name, header);
+    return value;
+};
+const fetchBytes = (client, source, url, headers, maxBytes) => client.execute(request(url, headers)).pipe(Effect.flatMap(HttpClientResponse.filterStatusOk), Effect.mapError((error) => sourceError(source, "Hosted skill request failed", error)), Effect.flatMap((response) => response.stream.pipe(Stream.mapError((error) => sourceError(source, "Hosted skill request failed", error)), Stream.runFoldEffect(() => ({ size: 0, chunks: [] }), (state, chunk) => {
+    const size = state.size + chunk.byteLength;
+    if (size > maxBytes) {
+        return Effect.fail(sourceError(source, `Hosted skill response exceeds ${maxBytes} bytes`));
+    }
+    state.chunks.push(chunk);
+    return Effect.succeed({ size, chunks: state.chunks });
+}), Effect.map(({ chunks, size }) => {
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}))));
+const decodeText = (source, bytes) => Effect.try({
+    try: () => decoder.decode(bytes),
+    catch: (cause) => sourceError(source, "Hosted skill response is not valid UTF-8", cause),
+});
+const frontmatter = (entry) => ({
+    name: entry.name,
+    description: entry.description,
+    ...(entry.whenToUse === undefined ? {} : { whenToUse: entry.whenToUse }),
+    ...(entry.allowedTools === undefined ? {} : { allowedTools: entry.allowedTools }),
+    ...(entry.disableModelInvocation === undefined ? {} : { disableModelInvocation: entry.disableModelInvocation }),
+    ...(entry.userInvocable === undefined ? {} : { userInvocable: entry.userInvocable }),
+    ...(entry.contextFork === undefined ? {} : { contextFork: entry.contextFork }),
+    ...(entry.agent === undefined ? {} : { agent: entry.agent }),
+    ...(entry.model === undefined ? {} : { model: entry.model }),
+    ...(entry.paths === undefined ? {} : { paths: entry.paths }),
+});
+const sameFrontmatter = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+/** @experimental Validate one safe relative SKILL.md path. */
+export const validateSkillPath = (source, skillPath) => {
+    const segments = skillPath.split("/");
+    return skillPath.length > 0 &&
+        !skillPath.startsWith("/") &&
+        !skillPath.includes("\\") &&
+        !skillPath.includes("%") &&
+        !skillPath.includes("?") &&
+        !skillPath.includes("#") &&
+        segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..")
+        ? Effect.succeed(skillPath)
+        : Effect.fail(sourceError(source, `Unsafe hosted skill path: ${skillPath}`));
+};
+/** @experimental Resolve a same-origin path beneath a manifest directory. */
+export const resolveRelative = (source, manifestUrl, skillPath) => Effect.gen(function* () {
+    yield* validateSkillPath(source, skillPath);
+    const manifest = yield* Effect.fromResult(Url.fromString(manifestUrl)).pipe(Effect.mapError((error) => sourceError(source, "Invalid manifest URL", error)));
+    const directory = yield* Effect.fromResult(Url.fromString(".", manifest)).pipe(Effect.mapError((error) => sourceError(source, "Invalid manifest directory URL", error)));
+    const resolved = yield* Effect.fromResult(Url.fromString(skillPath, directory)).pipe(Effect.mapError((error) => sourceError(source, "Invalid hosted skill URL", error)));
+    if (resolved.origin !== manifest.origin || !resolved.pathname.startsWith(directory.pathname)) {
+        return yield* Effect.fail(sourceError(source, `Hosted skill path escapes manifest directory: ${skillPath}`));
+    }
+    return resolved.toString();
+});
+/** @experimental Build a hosted manifest source over Effect HTTP and Crypto services. */
+export const make = (options) => Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const crypto = yield* Crypto.Crypto;
+    const manifestMaxBytes = yield* safeInteger(options.source, "manifestMaxBytes", options.manifestMaxBytes ?? 1024 * 1024, 1);
+    const bodyMaxBytes = yield* safeInteger(options.source, "bodyMaxBytes", options.bodyMaxBytes ?? 1024 * 1024, 1);
+    const maxSkills = yield* safeInteger(options.source, "maxSkills", options.maxSkills ?? 1_000, 1);
+    const descriptionCap = yield* safeInteger(options.source, "descriptionCap", options.descriptionCap ?? SkillSource.DESCRIPTION_CAP, 0);
+    const manifestBytes = yield* fetchBytes(client, options.source, options.manifestUrl, options.manifestHeaders, manifestMaxBytes);
+    const manifestText = yield* decodeText(options.source, manifestBytes);
+    const manifest = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Manifest))(manifestText).pipe(Effect.mapError((error) => sourceError(options.source, "Invalid hosted skill manifest", error)));
+    if (manifest.skills.length > maxSkills) {
+        return yield* Effect.fail(sourceError(options.source, `Hosted skill manifest exceeds ${maxSkills} skills`));
+    }
+    const byName = new Map();
+    for (const entry of manifest.skills) {
+        yield* validateName(options.source, entry.name);
+        if (entry.description.length === 0 || entry.description.length > 1_024) {
+            return yield* Effect.fail(sourceError(options.source, "Hosted skill description must contain 1-1024 characters"));
+        }
+        if (!/^[0-9a-f]{64}$/.test(entry.sha256)) {
+            return yield* Effect.fail(sourceError(options.source, `Invalid SHA-256 for hosted skill ${entry.name}`));
+        }
+        if (byName.has(entry.name)) {
+            return yield* Effect.fail(sourceError(options.source, `Duplicate hosted skill name: ${entry.name}`));
+        }
+        const pathSegments = entry.skillPath.split("/");
+        if (pathSegments.at(-1) !== "SKILL.md" || pathSegments.at(-2) !== entry.name) {
+            return yield* Effect.fail(sourceError(options.source, `Hosted skill path directory must match skill name: ${entry.name}`));
+        }
+        const skillUrl = yield* options.resolveSkillUrl(entry.skillPath);
+        const metadata = frontmatter(entry);
+        const body = fetchBytes(client, options.source, skillUrl, options.bodyHeaders, bodyMaxBytes).pipe(Effect.flatMap((bytes) => crypto.digest("SHA-256", bytes).pipe(Effect.mapError((error) => sourceError(options.source, `Unable to hash hosted skill ${entry.name}`, error)), Effect.flatMap((actual) => Encoding.encodeHex(actual) === entry.sha256
+            ? decodeText(options.source, bytes)
+            : Effect.fail(sourceError(options.source, `SHA-256 mismatch for hosted skill ${entry.name}`))))), Effect.flatMap((content) => parseDocument(options.source, content, entry.name).pipe(Effect.flatMap((document) => sameFrontmatter(document.frontmatter, metadata)
+            ? Effect.succeed(document.body)
+            : Effect.fail(sourceError(options.source, `Frontmatter mismatch for hosted skill ${entry.name}`))))));
+        const tools = options.toolsBySkill !== undefined && Object.hasOwn(options.toolsBySkill, entry.name)
+            ? (options.toolsBySkill[entry.name] ?? [])
+            : [];
+        byName.set(entry.name, {
+            frontmatter: metadata,
+            listing: SkillSource.makeListing(metadata, descriptionCap),
+            body,
+            tools,
+        });
+    }
+    const skills = [...byName.values()];
+    return {
+        all: Effect.succeed(skills),
+        get: (name) => Effect.succeed(byName.get(name)),
+    };
+});
+/** @experimental One-source hosted catalog layer. */
+export const layer = (options) => Layer.effect(SkillSource.SkillSource, make(options).pipe(Effect.map(SkillSource.SkillSource.of)));

package/dist/http-catalog.d.ts

@@ -0,0 +1,13 @@
+import { Crypto } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { SkillSource } from "@batonfx/core";
+import { type Limits } from "./hosted-catalog.js";
+/** @experimental Generic HTTP skill catalog options. */
+export interface Options extends Limits {
+    readonly manifestUrl: string;
+    readonly source?: string;
+}
+/** @experimental Build a generic HTTP catalog source. */
+export declare const make: (options: Options) => SkillSource.Source<HttpClient.HttpClient | Crypto.Crypto>;
+/** @experimental Build a generic HTTP catalog layer. */
+export declare const layer: (options: Options) => import("effect/Layer").Layer<SkillSource.SkillSource, SkillSource.SkillSourceError, HttpClient.HttpClient | Crypto.Crypto>;

package/dist/http-catalog.js

@@ -0,0 +1,19 @@
+import { Crypto, Effect } from "effect";
+import { HttpClient, Url } from "effect/unstable/http";
+import { SkillSource } from "@batonfx/core";
+import { make as makeHostedCatalog, resolveRelative } from "./hosted-catalog.js";
+const invalidUrl = (cause) => new SkillSource.SkillSourceError({ source: "http-skill-catalog", message: "Invalid manifest URL", cause });
+/** @experimental Build a generic HTTP catalog source. */
+export const make = (options) => {
+    return Effect.gen(function* () {
+        const parsed = yield* Effect.fromResult(Url.fromString(options.manifestUrl)).pipe(Effect.mapError(invalidUrl));
+        const source = options.source ?? `${parsed.origin}${parsed.pathname}`;
+        return yield* makeHostedCatalog({
+            ...options,
+            source,
+            resolveSkillUrl: (skillPath) => resolveRelative(source, options.manifestUrl, skillPath),
+        });
+    });
+};
+/** @experimental Build a generic HTTP catalog layer. */
+export const layer = (options) => SkillSource.layer([make(options)]);

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * as GitHubCatalog from "./github-catalog.js";
+export * as HostedCatalog from "./hosted-catalog.js";
+export * as HttpCatalog from "./http-catalog.js";
+export * as InstructionFiles from "./instructions-files.js";
+export * as S3Catalog from "./s3-catalog.js";
+export * as SkillLoader from "./skill-loader.js";