agents/dist/catalog-BpiVV1OF.d.ts

A home for your AI agents

import {
  d as SkillResourceInfo,
  h as SkillResult,
  i as SkillParseError,
  l as InvalidSkillResourcePathError,
  n as Skill,
  u as SkillResource
} from "./skill-DRBcIBjC.js";
import {
  a as SkillSource,
  i as SkillResourceNotFoundError,
  o as SkillSourceError
} from "./source-9RQzlEhM.js";

//#region src/skills/catalog.d.ts
/**
 * The skills an agent can use right now, merged from its sources.
 *
 * Load one with {@link loadSkillCatalog}; load it again to pick up changes.
 * Framework adapters (Think's AI SDK tools, the pi `skills()` extension)
 * wrap a catalog so every framework shows the model the same catalog text,
 * activation output, and resource output.
 */
interface SkillCatalog {
  /** Changes whenever {@link prompt} would change. */
  readonly fingerprint: string;
  /** Skills the model may activate, in source priority order. */
  readonly skills: readonly SkillCatalogEntry[];
  /** Problems found while loading: invalid skills, failed sources, duplicates. */
  readonly diagnostics: readonly SkillDiagnostic[];
  /**
   * System-prompt text listing each skill's name and description.
   *
   * @returns The catalog prompt, or `null` when there are no skills.
   */
  prompt(): string | null;
  /**
   * Find a skill by name.
   *
   * @param name - Skill name.
   * @returns The entry, or `undefined` when the catalog has no such skill.
   */
  find(name: string): SkillCatalogEntry | undefined;
  /**
   * Render a skill's instructions and resource list for the model.
   *
   * @param name - Skill name.
   */
  activate(name: string): SkillResult<string, UnknownSkillError>;
  /**
   * Read a bundled file.
   *
   * @param request - Either `name` and a skill-relative `path`, or a
   * qualified `path` such as `my-skill/references/guide.md`.
   */
  readResource(request: {
    readonly name?: string;
    readonly path: string;
  }): Promise<SkillResult<SkillCatalogResource, SkillResourceError>>;
}
/** A skill in a {@link SkillCatalog}. */
interface SkillCatalogEntry {
  /** The parsed skill. */
  readonly skill: Skill;
  /** Id of the source that provided it. */
  readonly sourceId: string;
  /** Files bundled with the skill. */
  readonly resources: readonly SkillResourceInfo[];
  /** Absolute directory in the agent's filesystem, when the source has one. */
  readonly location?: string;
}
/** A resource read through a {@link SkillCatalog}. */
interface SkillCatalogResource {
  /** The skill that owns the resource. */
  readonly entry: SkillCatalogEntry;
  /** The resource and its content. */
  readonly resource: SkillResource;
}
/** Why {@link SkillCatalog.readResource} failed. */
type SkillResourceError =
  | UnknownSkillError
  | InvalidSkillResourcePathError
  | SkillResourceNotFoundError
  | SkillSourceError;
/** A problem found while loading a catalog. Never fatal. */
type SkillDiagnostic =
  | {
      /** A `SKILL.md` broke a spec rule and was skipped. */ readonly _tag: "InvalidSkill";
      readonly sourceId: string;
      readonly location: string;
      readonly error: SkillParseError;
    }
  | {
      /**
       * A source could not be listed. With `previous`, its skills from the
       * previous catalog are kept (`keptPrevious`); otherwise it is skipped.
       */
      readonly _tag: "SourceFailed";
      readonly sourceId: string;
      readonly error: SkillSourceError;
      readonly keptPrevious: boolean;
    }
  | {
      /** A skill breaks a spec rule but was loaded anyway. */ readonly _tag: "SkillWarning";
      readonly sourceId: string;
      readonly name: string;
      readonly error: SkillParseError;
    }
  | {
      /** A later source listed a name an earlier source already provided. */ readonly _tag: "DuplicateSkill";
      readonly name: string;
      readonly sourceId: string;
      readonly keptSourceId: string;
    };
/** The catalog has no skill with the requested name. */
declare class UnknownSkillError extends Error {
  readonly skill: string;
  /** Stable tag for narrowing. */
  readonly _tag: "UnknownSkillError";
  /** @param skill - The requested name. */
  constructor(skill: string);
}
/** Options for {@link loadSkillCatalog}. */
interface LoadSkillCatalogOptions {
  /**
   * The catalog this load replaces. When a source fails to list, its skills
   * from `previous` are kept, so a transient outage does not remove working
   * skills from the prompt and tools. Sources are matched by identity.
   */
  readonly previous?: SkillCatalog;
}
/**
 * Load every source and merge them into a catalog.
 *
 * Sources apply in order: the first source to list a name wins. A failing
 * source or an invalid skill becomes a diagnostic instead of an error, so
 * one bad source never hides the others. Skills that set
 * `disable-model-invocation: true` are left out.
 *
 * @param sources - Skill sources in priority order.
 * @param options - Pass `previous` to keep a failing source's last skills.
 * @returns The merged catalog.
 */
declare function loadSkillCatalog(
  sources: readonly SkillSource[],
  options?: LoadSkillCatalogOptions
): Promise<SkillCatalog>;
/**
 * Describe a diagnostic in one line, for logs.
 *
 * @param diagnostic - A diagnostic from {@link SkillCatalog.diagnostics}.
 */
declare function formatSkillDiagnostic(diagnostic: SkillDiagnostic): string;
/**
 * Render a resource read for the model.
 *
 * @param read - A resource returned by {@link SkillCatalog.readResource}.
 */
declare function renderSkillResource(read: SkillCatalogResource): string;
//#endregion
export {
  SkillDiagnostic as a,
  formatSkillDiagnostic as c,
  SkillCatalogResource as i,
  loadSkillCatalog as l,
  SkillCatalog as n,
  SkillResourceError as o,
  SkillCatalogEntry as r,
  UnknownSkillError as s,
  LoadSkillCatalogOptions as t,
  renderSkillResource as u
};
//# sourceMappingURL=catalog-BpiVV1OF.d.ts.map