@getbourdon/participants 0.5.6 → 0.6.0

package/dist/readers/claude-code.d.ts

@@ -15,8 +15,9 @@
  * federation. Entities are deduped by case-insensitive name and sorted
  * alphabetically.
  */
-import { type L5ManifestModel, type SessionModel } from "@getbourdon/l5";
+import { type L5ManifestModel, type SessionModel, type SkillRefModel } from "@getbourdon/l5";
 import { type AgentStore, type BourdonParticipant, type HealthStatus } from "../base.js";
+import { type SkillScanReport, type SkillSource } from "../skills.js";
 /** Directory names for the knowledge repo. Only these are scanned. */
 export declare const BRAIN_DIR_NAMES: readonly [string];
 /** Env override pointing at the knowledge repo explicitly. */
@@ -32,7 +33,25 @@ export declare class ClaudeCodeParticipant implements BourdonParticipant {
     autoMemoryPath: string | null;
     knowledgeGraphPath: string | null;
     static defaultNativePath(home?: string): string;
-    constructor();
+    /**
+     * Explicit skill directories; `null` = the defaults (see skills.ts), read
+     * only for shared skills unless `BOURDON_SKILLS_ADVERTISE` lists all.
+     * Explicit sources list every skill in them.
+     */
+    private readonly explicitSkillSources;
+    constructor(options?: {
+        skillSources?: readonly SkillSource[] | null;
+    });
+    /**
+     * `~/.claude/skills` (or the config-dir override) and the cross-agent store,
+     * plus the opted-in projects' `.claude/skills` and `.agents/skills`.
+     */
+    /** Built with explicit skill sources: this participant lists all of them. */
+    hasExplicitSkillSources(): boolean;
+    skillSources(): SkillSource[];
+    /** Advertised skills plus the skills that could not be advertised. */
+    scanSkills(): SkillScanReport;
+    exportSkills(): SkillRefModel[];
     discover(): AgentStore;
     exportL5(since?: Date): L5ManifestModel;
     exportSessions(since?: Date, limit?: number): SessionModel[];

package/dist/readers/claude-code.js

@@ -23,6 +23,7 @@ import { parse as yamlParse } from "yaml";
 import { Visibility, filterForFederation, makeAgentInfo, makeEntity, makeManifest, makeSession, makeVisibilityPolicy, } from "@getbourdon/l5";
 import { containsSecret } from "@getbourdon/redaction";
 import { ParticipantDiscoveryError, SPEC_VERSION, } from "../base.js";
+import { advertisedSkills, claudeCodeSkillSources, crossAgentSkillSources, scanSkillSources, } from "../skills.js";
 const AGENT_ID = "claude-code";
 const AGENT_TYPE = "code-assistant";
 const ROLE_NARRATIVE = "Agentic manager and code-assistant. Coordinates the agent fleet, " +
@@ -478,11 +479,39 @@ export class ClaudeCodeParticipant {
     static defaultNativePath(home) {
         return join(home ?? homeDir(), ".claude");
     }
-    constructor() {
+    /**
+     * Explicit skill directories; `null` = the defaults (see skills.ts), read
+     * only for shared skills unless `BOURDON_SKILLS_ADVERTISE` lists all.
+     * Explicit sources list every skill in them.
+     */
+    explicitSkillSources;
+    constructor(options = {}) {
         this.nativePath = join(homeDir(), BRAIN_DIR_NAMES[0]); // primary anchor
         this.brainPath = resolveBrainPath();
         this.autoMemoryPath = resolveAutoMemoryPath();
         this.knowledgeGraphPath = resolveKnowledgeGraphPath();
+        this.explicitSkillSources = options.skillSources == null ? null : [...options.skillSources];
+    }
+    // -- Skills (plan 005: discovery only) -----------------------------------------
+    /**
+     * `~/.claude/skills` (or the config-dir override) and the cross-agent store,
+     * plus the opted-in projects' `.claude/skills` and `.agents/skills`.
+     */
+    /** Built with explicit skill sources: this participant lists all of them. */
+    hasExplicitSkillSources() {
+        return this.explicitSkillSources !== null;
+    }
+    skillSources() {
+        if (this.explicitSkillSources !== null)
+            return [...this.explicitSkillSources];
+        return [...claudeCodeSkillSources(), ...crossAgentSkillSources()];
+    }
+    /** Advertised skills plus the skills that could not be advertised. */
+    scanSkills() {
+        return scanSkillSources(this.skillSources());
+    }
+    exportSkills() {
+        return this.scanSkills().refs;
     }
     discover() {
         const sources = {
@@ -531,6 +560,7 @@ export class ClaudeCodeParticipant {
             recent_sessions: sessions,
             known_entities: visibleEntities,
             visibility_policy: DEFAULT_POLICY,
+            skills: advertisedSkills(this),
         });
     }
     exportSessions(since, limit = 100) {

package/dist/readers/cursor.d.ts

@@ -18,8 +18,9 @@
  * deterministic, visibility-enforced-before-emission, redaction on every native
  * string; `healthCheck` never throws.
  */
-import { type L5ManifestModel, type SessionModel } from "@getbourdon/l5";
+import { type L5ManifestModel, type SessionModel, type SkillRefModel } from "@getbourdon/l5";
 import { type AgentStore, type BourdonParticipant, type HealthStatus } from "../base.js";
+import { type SkillScanReport, type SkillSource } from "../skills.js";
 /**
  * Platform-specific Cursor data dir (the SQLite workspace state lives here),
  * `$CURSOR_DIR` override first. Returns null on an unrecognized platform (or
@@ -40,7 +41,27 @@ export declare class CursorParticipant implements BourdonParticipant {
      * extraction intentionally use different anchors.
      */
     static defaultNativePath(home?: string): string;
-    constructor(cursorDir?: string | null, workspaceRoot?: string | null);
+    /**
+     * Explicit skill directories; `null` = the defaults (see skills.ts), read
+     * only for shared skills unless `BOURDON_SKILLS_ADVERTISE` lists all.
+     * Explicit sources list every skill in them.
+     * `workspaceRoot` does not opt a project in: that takes an explicit
+     * `BOURDON_SKILL_PROJECTS` entry, or explicit sources.
+     */
+    private readonly explicitSkillSources;
+    constructor(cursorDir?: string | null, workspaceRoot?: string | null, options?: {
+        skillSources?: readonly SkillSource[] | null;
+    });
+    /**
+     * `~/.cursor/skills` (not the built-in `skills-cursor`) and the cross-agent
+     * store, plus the opted-in projects' `.cursor/skills` and `.agents/skills`.
+     */
+    /** Built with explicit skill sources: this participant lists all of them. */
+    hasExplicitSkillSources(): boolean;
+    skillSources(): SkillSource[];
+    /** Advertised skills plus the skills that could not be advertised. */
+    scanSkills(): SkillScanReport;
+    exportSkills(): SkillRefModel[];
     get nativePath(): string;
     discover(): AgentStore;
     exportSessions(since?: Date, limit?: number): SessionModel[];

package/dist/readers/cursor.js

@@ -25,6 +25,7 @@ import { basename, join } from "node:path";
 import { Visibility, filterForFederation, makeAgentInfo, makeEntity, makeManifest, makeSession, makeVisibilityPolicy, } from "@getbourdon/l5";
 import { redactText } from "@getbourdon/redaction";
 import { ParticipantDiscoveryError, SPEC_VERSION, } from "../base.js";
+import { advertisedSkills, crossAgentSkillSources, cursorSkillSources, scanSkillSources, } from "../skills.js";
 import { tableExists, tryOpenReadonly } from "../sqlite-base.js";
 const AGENT_ID = "cursor";
 const AGENT_TYPE = "code-assistant";
@@ -529,9 +530,39 @@ export class CursorParticipant {
     static defaultNativePath(home) {
         return join(home ?? homeDir(), ".cursor");
     }
-    constructor(cursorDir, workspaceRoot) {
+    /**
+     * Explicit skill directories; `null` = the defaults (see skills.ts), read
+     * only for shared skills unless `BOURDON_SKILLS_ADVERTISE` lists all.
+     * Explicit sources list every skill in them.
+     * `workspaceRoot` does not opt a project in: that takes an explicit
+     * `BOURDON_SKILL_PROJECTS` entry, or explicit sources.
+     */
+    explicitSkillSources;
+    constructor(cursorDir, workspaceRoot, options = {}) {
         this.cursorDir = cursorDir ?? null;
         this.workspaceRoot = workspaceRoot ?? null;
+        this.explicitSkillSources = options.skillSources == null ? null : [...options.skillSources];
+    }
+    // -- Skills (plan 005: discovery only) -----------------------------------------
+    /**
+     * `~/.cursor/skills` (not the built-in `skills-cursor`) and the cross-agent
+     * store, plus the opted-in projects' `.cursor/skills` and `.agents/skills`.
+     */
+    /** Built with explicit skill sources: this participant lists all of them. */
+    hasExplicitSkillSources() {
+        return this.explicitSkillSources !== null;
+    }
+    skillSources() {
+        if (this.explicitSkillSources !== null)
+            return [...this.explicitSkillSources];
+        return [...cursorSkillSources(), ...crossAgentSkillSources()];
+    }
+    /** Advertised skills plus the skills that could not be advertised. */
+    scanSkills() {
+        return scanSkillSources(this.skillSources());
+    }
+    exportSkills() {
+        return this.scanSkills().refs;
     }
     get nativePath() {
         const path = this.cursorDir ?? defaultCursorDir();
@@ -609,6 +640,7 @@ export class CursorParticipant {
             recent_sessions: sessions,
             known_entities: visibleEntities,
             visibility_policy: this.policy,
+            skills: advertisedSkills(this),
         });
     }
     healthCheck() {

package/dist/skill-index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Reader-side skill folder scan (plan 005). Port of the parts of the engine's
+ * `core/skill_index.py` a participant needs to advertise a local skill: the
+ * text-only content rules, the no-follow folder walk, front-matter parsing,
+ * the `content_sha256` framing and `scan_local_skill` (skip and flag).
+ *
+ * `readSkillFolder` is the promotion-side twin of `scanLocalSkill`: it refuses
+ * a folder that breaks any rule instead of skipping files. The library-level
+ * shared store (index rows, versions, promotion) is in `skill-store.ts`. Both
+ * use the same limits and name rule, so a hash computed here compares
+ * directly with a shared skill's.
+ *
+ * Rules a v1 shared skill must meet (anything else is skipped and flagged):
+ *  - `SKILL.md` plus markdown, plain text and template files only;
+ *  - no links, no hidden entries, bounded depth and path length, no paths that
+ *    differ only in case;
+ *  - UTF-8 text without NUL bytes, no interpreter line, no credential-like text;
+ *  - per-file and total size caps, at most {@link MAX_REFERENCE_FILES} reference files.
+ */
+import { type Stats } from "node:fs";
+export declare const SKILL_BODY_NAME = "SKILL.md";
+/** Reference-file types a v1 shared skill may carry: markdown, plain text and templates. */
+export declare const TEXT_FILE_SUFFIXES: ReadonlySet<string>;
+export declare const MAX_SKILL_BODY_BYTES: number;
+export declare const MAX_REFERENCE_FILE_BYTES: number;
+export declare const MAX_REFERENCE_FILES = 64;
+export declare const MAX_SKILL_TOTAL_BYTES: number;
+/**
+ * Why a reader left a file out of an advertised skill. `limit` means the
+ * file-count or total-size cap was reached; every other code names the content
+ * rule the file breaks.
+ */
+export declare const SKIP_REASONS: ReadonlySet<string>;
+/** Longest skill name, in code points. */
+export declare const SKILL_NAME_MAX: number;
+/** Longest front-matter description, in code points. */
+export declare const SKILL_DESCRIPTION_MAX: number;
+/**
+ * A skill folder cannot be advertised (or shared) as it stands. `problems`
+ * lists every offending path with the reason; content is never echoed back.
+ */
+export declare class SkillContentError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/** Python `str.strip()` with no argument. */
+export declare function pyStrip(text: string): string;
+/** Length in code points, as Python's `len(str)`. */
+export declare function codePointLength(text: string): number;
+/** The first `limit` code points, as Python's `text[:limit]`. */
+export declare function codePointSlice(text: string, limit: number): string;
+/** Code-point order (Python's str order), via the UTF-8 bytes. */
+export declare function compareUtf8(a: string, b: string): number;
+/** Whether `path` is a symbolic link (on Windows, a junction or symlink reparse point). */
+export declare function isPathLinkOrReparse(path: string, stats?: Stats): boolean;
+export interface SkillFrontMatter {
+    name: string;
+    description: string;
+}
+/** Why `value` is not a valid skill name (`label` names the field), or null. */
+export declare function skillNameError(value: unknown, label?: string): string | null;
+/** Extract `name` and `description` from a `SKILL.md` body. Throws {@link SkillContentError}. */
+export declare function parseFrontMatter(body: Uint8Array | string): SkillFrontMatter;
+/**
+ * Hash a skill's files as the schema's `content_sha256` defines: entries sorted
+ * by the UTF-8 bytes of their POSIX path relative to the skill folder, each
+ * framed as `path \0 len(bytes) \0 bytes`.
+ */
+export declare function computeContentSha256(entries: Iterable<readonly [string, Uint8Array]>): string;
+/** One file a reader left out of a local skill, and why (a {@link SKIP_REASONS} code). */
+export interface SkippedFile {
+    path: string;
+    reason: string;
+}
+/**
+ * What a participant reader can advertise about one local skill folder. `files`
+ * is the shareable part (`SKILL.md` plus every reference file that passes the
+ * v1 content rules); `skipped` lists the rest. The hash covers `files` only.
+ */
+export interface LocalSkillScan {
+    frontMatter: SkillFrontMatter;
+    files: ReadonlyArray<readonly [string, Uint8Array]>;
+    skipped: readonly SkippedFile[];
+    contentSha256: string;
+}
+/**
+ * Scan one local skill folder for discovery: skip and flag, don't refuse.
+ *
+ * A disallowed reference file (a script, a binary, a link, a hidden file,
+ * credential-like text) is left out and reported in `skipped` instead of making
+ * the whole skill disappear. Only a `SKILL.md` that is missing, unreadable or
+ * itself breaks a content rule throws {@link SkillContentError}, because then
+ * there is nothing safe to advertise. Nothing is followed through a link and
+ * nothing is modified.
+ */
+export declare function scanLocalSkill(folder: string): LocalSkillScan;
+/** A validated skill: front matter plus every file, `SKILL.md` included, sorted by path. */
+export interface SkillContent {
+    frontMatter: SkillFrontMatter;
+    files: ReadonlyArray<readonly [string, Uint8Array]>;
+}
+/** The `SKILL.md` bytes of `content`. */
+export declare function skillContentBody(content: SkillContent): Uint8Array;
+/**
+ * Read a skill folder and enforce every v1 content rule (the oracle's
+ * `read_skill_folder`). Throws {@link SkillContentError} listing every problem
+ * found. The folder is read in place and never modified; links are reported,
+ * never followed.
+ */
+export declare function readSkillFolder(folder: string): SkillContent;