@getbourdon/participants 0.5.5 → 0.6.0

package/dist/skills.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Skill readers: advertise the local skills an agent can see in its L5
+ * manifest (plan 005, discovery side). Port of `participants/_skills.py`.
+ *
+ * A participant that knows where its agent keeps skills (a folder per skill
+ * holding a `SKILL.md` with `name` / `description` front matter) lists them as
+ * `SkillRef` rows: name, description and a content hash. Nothing is shared or
+ * promoted here; the body never enters the manifest.
+ *
+ * Two kinds of skill directory:
+ *  - **The agent's own** (`~/.claude/skills`, `$CODEX_HOME/skills`,
+ *    `~/.cursor/skills` and their project forms).
+ *  - **The cross-agent store**, `~/.agents/skills` (and `<project>/.agents/skills`):
+ *    a vendor-neutral directory no single agent owns. The cross-agent skills
+ *    installer CLI keeps its installs there and records each one in
+ *    `~/.agents/.skill-lock.json`; people also write skills there by hand. Refs
+ *    from it carry `store: cross_agent`. Every skill-reading participant reads
+ *    it with its own directories; a reader of several manifests collapses the
+ *    copies (`collectAdvertisedSkills` in @getbourdon/federation).
+ *
+ * One skill, one ref per manifest: when an agent's own folder holds a skill
+ * that is also in the cross-agent store, the agent-folder ref is kept and
+ * records the store copy in `also_in` (`via: copy` for a copy with the same
+ * `content_sha256`, `via: link` for a link into the store); the store's own ref
+ * is then left out. A link counts only when it resolves to a direct child
+ * folder of the store at the same scope, and the skill is then read through
+ * the store's own path, never through the link. Any other link is skipped.
+ *
+ * Provenance (user-level store only): a skill with an entry in the installer
+ * lock carries `origin: {kind: installed, ...}`; one without carries
+ * `origin: {kind: authored}`. Nothing else is read from the lock, and a
+ * missing, linked, oversized or malformed lock never fails a scan.
+ *
+ * Scope: one skill at a time. By default a participant lists only the skills
+ * the person approved one by one with `bourdon skills share` (stored locally
+ * in `<library>/.skill-shares.json`, see skill-shares.ts), and only while the
+ * folder still hashes to the approved content; no other skill folder is read.
+ * `BOURDON_SKILLS_ADVERTISE` set to an on value lists every skill; an off
+ * value or an unrecognised one lists none, shared or not. A caller that builds
+ * a participant with explicit `skillSources` lists every skill in them
+ * ({@link skillsListingMode}). The directories: user-level skill directories,
+ * and a project's directories
+ * only when the project is named in `BOURDON_SKILL_PROJECTS` (absolute paths
+ * separated by the platform's path delimiter). Disallowed files are skipped
+ * and flagged, never fatal; no link is followed; no absolute path reaches the
+ * manifest (`path_hint` starts at a symbolic root); refs are emitted as
+ * `team`.
+ */
+import { type SkillOriginModel, type SkillRefModel } from "@getbourdon/l5";
+/** Opt-in list of project roots whose skill directories may be indexed. */
+export declare const SKILL_PROJECTS_ENV = "BOURDON_SKILL_PROJECTS";
+/**
+ * The listing switch for every participant. Skill descriptions are free text
+ * and can name private projects, clients or infrastructure, so by default
+ * (unset or empty) only the skills approved one by one are listed. `1` /
+ * `true` / `yes` / `on` list every skill; `0` / `false` / `no` / `off` list
+ * none, approved or not, and so does any other value (fail closed): a typo
+ * never lists anything.
+ */
+export declare const SKILLS_ADVERTISE_ENV = "BOURDON_SKILLS_ADVERTISE";
+/**
+ * Turns named participants off in every mode: agent ids separated by commas
+ * (or whitespace), e.g. `codex,cursor`. Matching ignores case.
+ */
+export declare const SKILLS_NO_ADVERTISE_ENV = "BOURDON_SKILLS_NO_ADVERTISE";
+/** {@link skillsListingMode} results. */
+export declare const LIST_ALL = "all";
+export declare const LIST_APPROVED = "approved";
+export declare const LIST_OFF = "off";
+export type SkillsListingMode = typeof LIST_ALL | typeof LIST_APPROVED | typeof LIST_OFF;
+/** Every advertised ref carries this visibility. */
+export declare const SKILL_REF_VISIBILITY: "team";
+/** The L5 schema bounds (`skills.maxItems` and the `SkillRef` fields). */
+export declare const MAX_SKILL_REFS = 512;
+export declare const MAX_SKIPPED_FILES = 32;
+export declare const MAX_PATH_HINT_CHARS = 255;
+export declare const MAX_PROJECT_NAME_CHARS = 128;
+export declare const MAX_ORIGIN_SOURCE_CHARS = 255;
+export declare const MAX_ORIGIN_URL_CHARS = 512;
+export declare const MAX_ORIGIN_SOURCE_TYPE_CHARS = 32;
+/** An installer lock larger than this is not read (origin is then omitted). */
+export declare const MAX_LOCK_BYTES: number;
+export declare const SCOPE_USER = "user";
+export declare const SCOPE_PROJECT = "project";
+/** Whose directory a skill folder sits in; `agent` is the default and never written. */
+export declare const STORE_AGENT = "agent";
+export declare const STORE_CROSS_AGENT = "cross_agent";
+export declare const VIA_COPY = "copy";
+export declare const VIA_LINK = "link";
+export declare const ORIGIN_INSTALLED = "installed";
+export declare const ORIGIN_AUTHORED = "authored";
+/** The cross-agent installer's lock file, beside the user-level store. */
+export declare const CROSS_AGENT_LOCK_NAME = ".skill-lock.json";
+/**
+ * One directory a reader indexes, one skill per child folder. `label` is the
+ * symbolic form of `root` that `path_hint` starts with; it never contains an
+ * absolute path. `store` says whose directory it is; `lockFile` is the
+ * installer lock that records where the store's skills came from.
+ */
+export interface SkillSource {
+    root: string;
+    scope: string;
+    label: string;
+    project?: string | null;
+    store?: string;
+    lockFile?: string | null;
+}
+/** A skill (or a whole skills directory) that was not advertised, and why. */
+export interface SkippedSkill {
+    pathHint: string;
+    scope: string;
+    reason: string;
+    project?: string | null;
+}
+export interface SkillScanReport {
+    refs: SkillRefModel[];
+    skipped: SkippedSkill[];
+}
+/** The home directory user-level skill directories are found under. */
+export declare function userHome(): string;
+/**
+ * Project roots opted in through {@link SKILL_PROJECTS_ENV}, in order. Only
+ * absolute paths count: a relative entry is ignored (and logged) rather than
+ * resolved against whatever directory the export happens to run in.
+ */
+export declare function skillProjects(): string[];
+export interface SkillSourceOptions {
+    /** The home directory to use instead of {@link userHome}. */
+    home?: string;
+    /** Project roots instead of {@link skillProjects}. */
+    projects?: readonly string[];
+}
+/**
+ * Claude Code: `<config dir>/skills` and, on opt-in, `<project>/.claude/skills`.
+ * The config directory is `CLAUDE_CONFIG_DIR` (Claude Code's own override),
+ * else `CLAUDE_HOME`, else `~/.claude`.
+ */
+export declare function claudeCodeSkillSources(options?: SkillSourceOptions): SkillSource[];
+/**
+ * Codex: `$CODEX_HOME/skills`. `codexHome` is an explicit Codex home, if one
+ * was given; otherwise `CODEX_HOME`, else `~/.codex`. Codex keeps its bundled
+ * skills in a hidden `.system` folder there, which is not indexed. The mirror
+ * has no Codex participant yet; this is the source a Codex reader would use.
+ */
+export declare function codexSkillSources(options?: {
+    codexHome?: string | null;
+    home?: string;
+}): SkillSource[];
+/**
+ * Cursor: `~/.cursor/skills` and, on opt-in, `<project>/.cursor/skills`.
+ * `CURSOR_HOME` overrides `~/.cursor`. `~/.cursor/skills-cursor` holds
+ * Cursor's own built-in skills and is not indexed.
+ */
+export declare function cursorSkillSources(options?: SkillSourceOptions): SkillSource[];
+/**
+ * The vendor-neutral store: `~/.agents/skills` and, on opt-in,
+ * `<project>/.agents/skills`. The user-level store comes with the installer
+ * lock for provenance; no lock is read for a project store.
+ */
+export declare function crossAgentSkillSources(options?: SkillSourceOptions): SkillSource[];
+type LockEntry = Record<string, unknown>;
+/**
+ * The `skills` table of the installer lock, keyed by skill name. An empty map
+ * when there is no lock (every store skill is then `authored`); `null` when a
+ * lock exists but cannot be trusted or parsed (a link, not a regular file, too
+ * large, not JSON, or without a `skills` mapping), in which case origin is left
+ * off rather than guessed.
+ */
+export declare function readInstallLock(path: string): Map<string, LockEntry> | null;
+/**
+ * `installed` with the lock entry's sanitised source fields, else `authored`.
+ * Reads only `source`, `sourceType`, `sourceUrl` and `updatedAt`; a field
+ * that is missing, of the wrong type or fails its check is left out.
+ */
+export declare function originFromLockEntry(entry: LockEntry | null | undefined): SkillOriginModel;
+/** Which child folders of a source to read: absent reads every one. */
+export type SkillFolderFilter = (source: SkillSource, folderName: string) => boolean;
+export interface ScanSkillSourcesOptions {
+    /**
+     * Limits the scan to the child folders it accepts; every other folder is
+     * passed over unread. A store folder that an accepted agent folder links to
+     * is read too, so the link resolves as in a full scan. An accepted agent
+     * folder that is a copy of a store folder the scan did not read carries no
+     * `also_in`.
+     */
+    include?: SkillFolderFilter | null;
+}
+/**
+ * Index every source; one ref per skill, first occurrence of a name wins per
+ * store and scope. Cross-agent stores are scanned first so the agent's own
+ * folders can be matched against them (`also_in`). Refs come back with the
+ * agent's own folders first, in source order, then the cross-agent store
+ * skills that no advertised agent folder already represents.
+ */
+export declare function scanSkillSources(sources: Iterable<SkillSource>, options?: ScanSkillSourcesOptions): SkillScanReport;
+/** A participant that advertises skills (plan 005). */
+export interface SkillAdvertiser {
+    agentId: string;
+    exportSkills(): SkillRefModel[];
+    /**
+     * Whether the participant was built with explicit `skillSources`, which
+     * lists every skill in them ({@link skillsListingMode}). Absent = no.
+     */
+    hasExplicitSkillSources?(): boolean;
+    /**
+     * The directories the reader indexes. When present, the default
+     * (approved-only) mode reads just the approved folders in them; without it
+     * the reader's own scan runs and only approved refs are kept.
+     */
+    skillSources?(): SkillSource[];
+}
+/**
+ * Which skills the participant `agentId` may list in its manifest.
+ *
+ *  - {@link LIST_APPROVED}: {@link SKILLS_ADVERTISE_ENV} unset or empty: only
+ *    the skills approved one by one (`bourdon skills share`) whose folder still
+ *    hashes to the approved content.
+ *  - {@link LIST_ALL}: an on value; or, while the variable is unset, a
+ *    participant built with explicit `skillSources` (the caller chose what to
+ *    index).
+ *  - {@link LIST_OFF}: an off value, or any unrecognised one (fail closed):
+ *    nothing is listed, approved or not.
+ *
+ * {@link SKILLS_NO_ADVERTISE_ENV} turns named participants off in every mode.
+ */
+export declare function skillsListingMode(agentId: string, options?: {
+    explicitSources?: boolean;
+}): SkillsListingMode;
+/**
+ * Whether the participant `agentId` lists every skill it can see: true only
+ * in {@link LIST_ALL} mode ({@link skillsListingMode}). In the default mode a
+ * participant lists only the skills shared one by one.
+ */
+export declare function skillsAdvertisingEnabled(agentId: string, options?: {
+    explicitSources?: boolean;
+}): boolean;
+/**
+ * The refs `participant`'s manifest carries, for `exportL5`.
+ *
+ * Follows {@link skillsListingMode}: nothing, and no skill directory read,
+ * when off; by default only the skills with a current approval, reading only
+ * their folders; every skill the reader sees when listing all. A participant
+ * built with explicit `skillSources` lists all unless turned off. A failure
+ * here never fails an export: skills are an addition to the manifest, not a
+ * reason to lose its memory rows. Private refs are dropped, as private
+ * entities are.
+ */
+export declare function advertisedSkills(participant: SkillAdvertiser): SkillRefModel[];
+/**
+ * The default skill directories of a built-in skill-reading participant.
+ *
+ * The same directories the participant's own export reads (its user-level
+ * directory honouring its home override, the opted-in projects, and the
+ * cross-agent store). `null` for an agent with no skill reader here, so a skill
+ * it advertises can be listed but not proposed from this machine.
+ */
+export declare function skillSourcesForAgent(agentId: string): SkillSource[] | null;
+/**
+ * The folder an advertised ref was scanned from, found through `sources` only.
+ *
+ * `ref` is a SkillRef as it sits in a manifest. Its `path_hint` is matched
+ * against each source's symbolic label (same scope and project), so the result
+ * is always one direct child of a directory the reader indexes; a path from
+ * anywhere else cannot be produced. A ref that is a link into the cross-agent
+ * store resolves to the store's own folder, as the reader read it. `null` when
+ * nothing matches.
+ */
+export declare function resolveAdvertisedFolder(sources: readonly SkillSource[], ref: Readonly<Record<string, unknown>>): string | null;
+/** The built-in skill readers, in listing order. */
+export declare const SKILL_READERS: readonly ["claude-code", "codex", "cursor"];
+/**
+ * One skill folder a built-in reader sees, for `bourdon skills available|share`.
+ *
+ * `agent` is the reader that owns the folder, or `null` for a cross-agent
+ * store folder; `agents` names every reader that sees it. Local use only:
+ * `folder` is an absolute path and never leaves the terminal command that
+ * asked for it.
+ */
+export interface LocalSkill {
+    ref: SkillRefModel;
+    agent: string | null;
+    agents: string[];
+    folder: string;
+    /** `agent` or `cross_agent`. */
+    store: string;
+}
+/**
+ * Every skill folder the built-in readers see on this machine (each one is
+ * read). The same directories the readers' exports use: user-level, opted-in
+ * projects and the cross-agent store. One row per folder; a store folder seen
+ * by several readers is one row naming them all. `agent` keeps the folders
+ * that one reader sees.
+ */
+export declare function localSkills(agent?: string | null): LocalSkill[];
+export {};