agents 0.30.1 → 0.32.0

package/dist/catalog-BpOejOsE.js

@@ -0,0 +1,239 @@
+import { c as isModelInvocable, d as err, f as ok, o as parseSkillResourcePath, t as InvalidSkillResourcePathError } from "./resource-B59OV2a2.js";
+//#region src/skills/source.ts
+/** A source's backing store failed. */
+var SkillSourceError = class extends Error {
+	/**
+	* @param sourceId - The source that failed.
+	* @param operation - What the source was doing.
+	* @param cause - The underlying store error.
+	*/
+	constructor(sourceId, operation, cause) {
+		super(`Skill source "${sourceId}" failed to ${operation === "list" ? "list skills" : "read a resource"}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+		this.sourceId = sourceId;
+		this.operation = operation;
+		this._tag = "SkillSourceError";
+		this.name = "SkillSourceError";
+	}
+};
+/** A skill has no file at the requested path. */
+var SkillResourceNotFoundError = class extends Error {
+	/**
+	* @param skill - The skill that was searched.
+	* @param path - The missing path.
+	*/
+	constructor(skill, path) {
+		super(`Resource not found: ${skill}/${path}`);
+		this.skill = skill;
+		this.path = path;
+		this._tag = "SkillResourceNotFoundError";
+		this.name = "SkillResourceNotFoundError";
+	}
+};
+//#endregion
+//#region src/skills/catalog.ts
+/** The catalog has no skill with the requested name. */
+var UnknownSkillError = class extends Error {
+	/** @param skill - The requested name. */
+	constructor(skill) {
+		super(`Skill not found: ${skill}`);
+		this.skill = skill;
+		this._tag = "UnknownSkillError";
+		this.name = "UnknownSkillError";
+	}
+};
+/**
+* Successful listings behind each catalog, by source object. Lets a later
+* load fall back to the last good listing of a failing source without
+* putting listings on the public catalog shape.
+*/
+const catalogListings = /* @__PURE__ */ new WeakMap();
+/**
+* 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.
+*/
+async function loadSkillCatalog(sources, options = {}) {
+	const previousListings = options.previous ? catalogListings.get(options.previous) : void 0;
+	const listings = await Promise.all(sources.map(async (source) => ({
+		source,
+		listed: await source.list().catch((cause) => err(new SkillSourceError(source.id, "list", cause)))
+	})));
+	const diagnostics = [];
+	const entries = /* @__PURE__ */ new Map();
+	const sourceBySkill = /* @__PURE__ */ new Map();
+	const goodListings = /* @__PURE__ */ new Map();
+	for (const { source, listed } of listings) {
+		let listing;
+		if (listed.ok) listing = listed.value;
+		else {
+			const fallback = previousListings?.get(source);
+			diagnostics.push({
+				_tag: "SourceFailed",
+				sourceId: source.id,
+				error: listed.error,
+				keptPrevious: fallback !== void 0
+			});
+			if (!fallback) continue;
+			listing = fallback;
+		}
+		goodListings.set(source, listing);
+		for (const invalid of listing.invalid) diagnostics.push({
+			_tag: "InvalidSkill",
+			sourceId: source.id,
+			location: invalid.location,
+			error: invalid.error
+		});
+		for (const { skill, resources, location, warnings } of listing.skills) {
+			const existing = entries.get(skill.name);
+			if (existing) {
+				diagnostics.push({
+					_tag: "DuplicateSkill",
+					name: skill.name,
+					sourceId: source.id,
+					keptSourceId: existing.sourceId
+				});
+				continue;
+			}
+			entries.set(skill.name, {
+				skill,
+				sourceId: source.id,
+				resources,
+				...location === void 0 ? {} : { location }
+			});
+			sourceBySkill.set(skill.name, source);
+			for (const warning of warnings ?? []) diagnostics.push({
+				_tag: "SkillWarning",
+				sourceId: source.id,
+				name: skill.name,
+				error: warning
+			});
+		}
+	}
+	const skills = [...entries.values()].filter((entry) => isModelInvocable(entry.skill));
+	const visible = new Map(skills.map((entry) => [entry.skill.name, entry]));
+	const prompt = renderCatalogPrompt(skills);
+	const catalog = {
+		fingerprint: fingerprintOf(prompt ?? ""),
+		skills,
+		diagnostics,
+		prompt: () => prompt,
+		find: (name) => visible.get(name),
+		activate(name) {
+			const entry = visible.get(name);
+			return entry ? ok(renderSkillActivation(entry)) : err(new UnknownSkillError(name));
+		},
+		async readResource(request) {
+			const target = resolveResourceTarget(visible, request);
+			if (!target.ok) return target;
+			const { entry, path } = target.value;
+			const source = sourceBySkill.get(entry.skill.name);
+			if (!source) return err(new UnknownSkillError(entry.skill.name));
+			const read = await source.readResource(entry.skill.name, path).catch((cause) => err(new SkillSourceError(source.id, "read-resource", cause)));
+			if (!read.ok) return read;
+			return ok({
+				entry,
+				resource: read.value
+			});
+		}
+	};
+	catalogListings.set(catalog, goodListings);
+	return catalog;
+}
+/**
+* Describe a diagnostic in one line, for logs.
+*
+* @param diagnostic - A diagnostic from {@link SkillCatalog.diagnostics}.
+*/
+function formatSkillDiagnostic(diagnostic) {
+	switch (diagnostic._tag) {
+		case "InvalidSkill": return `Skipped invalid skill ${diagnostic.location} from source "${diagnostic.sourceId}": ${diagnostic.error.message}`;
+		case "SkillWarning": return `Skill "${diagnostic.name}" from source "${diagnostic.sourceId}" breaks the Agent Skills spec but was loaded: ${diagnostic.error.message}`;
+		case "SourceFailed": return `${diagnostic.error.message}. ${diagnostic.keptPrevious ? "Its last listed skills were kept." : "Its skills were skipped."}`;
+		case "DuplicateSkill": return `Duplicate skill "${diagnostic.name}" from source "${diagnostic.sourceId}" ignored; already provided by "${diagnostic.keptSourceId}".`;
+	}
+}
+/**
+* Render a resource read for the model.
+*
+* @param read - A resource returned by {@link SkillCatalog.readResource}.
+*/
+function renderSkillResource(read) {
+	const { entry, resource } = read;
+	return [
+		`<skill_resource${attributes([
+			["name", entry.skill.name],
+			["path", resource.path],
+			["kind", resource.kind],
+			["encoding", resource.encoding],
+			["mimeType", resource.mimeType]
+		])}>`,
+		resource.content,
+		"</skill_resource>"
+	].join("\n");
+}
+function renderCatalogPrompt(skills) {
+	if (skills.length === 0) return null;
+	return [
+		"Available skills. When a task matches a skill, use activate_skill with its name before proceeding.",
+		"",
+		...skills.map(({ skill }) => `- ${skill.name}: ${skill.description.replace(/\s+/g, " ")}`)
+	].join("\n");
+}
+function renderSkillActivation(entry) {
+	const lines = [`<skill_content${attributes([["name", entry.skill.name], ["location", entry.location]])}>`, entry.skill.body.trim()];
+	if (entry.resources.length > 0) {
+		lines.push("", "<skill_resources>");
+		for (const resource of entry.resources) lines.push(`  <file${attributes([
+			["kind", resource.kind],
+			["encoding", resource.encoding],
+			["size", resource.size === void 0 ? void 0 : String(resource.size)]
+		])}>${resource.path}</file>`);
+		lines.push("</skill_resources>");
+	}
+	lines.push("</skill_content>");
+	return lines.join("\n");
+}
+function resolveResourceTarget(skills, request) {
+	let name = request.name;
+	let relative = request.path;
+	if (name === void 0) {
+		const slash = relative.indexOf("/");
+		if (slash <= 0) return err(new InvalidSkillResourcePathError(relative));
+		name = relative.slice(0, slash);
+		relative = relative.slice(slash + 1);
+	}
+	const entry = skills.get(name);
+	if (!entry) return err(new UnknownSkillError(name));
+	const path = parseSkillResourcePath(relative);
+	if (!path.ok) return path;
+	if (!entry.resources.some((resource) => resource.path === path.value)) return err(new SkillResourceNotFoundError(entry.skill.name, path.value));
+	return ok({
+		entry,
+		path: path.value
+	});
+}
+function attributes(pairs) {
+	return pairs.filter((pair) => pair[1] !== void 0).map(([key, value]) => ` ${key}="${value.replace(/"/g, "&quot;")}"`).join("");
+}
+/** Two FNV-1a passes with different seeds: cheap and stable across isolates. */
+function fingerprintOf(text) {
+	let a = 2166136261;
+	let b = 16777619;
+	for (let index = 0; index < text.length; index++) {
+		const code = text.charCodeAt(index);
+		a = Math.imul(a ^ code, 16777619);
+		b = Math.imul(b ^ code, 2166136261);
+	}
+	return `${(a >>> 0).toString(16).padStart(8, "0")}${(b >>> 0).toString(16).padStart(8, "0")}`;
+}
+//#endregion
+export { SkillResourceNotFoundError as a, renderSkillResource as i, formatSkillDiagnostic as n, SkillSourceError as o, loadSkillCatalog as r, UnknownSkillError as t };
+
+//# sourceMappingURL=catalog-BpOejOsE.js.map

package/dist/catalog-BpOejOsE.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-BpOejOsE.js","names":[],"sources":["../src/skills/source.ts","../src/skills/catalog.ts"],"sourcesContent":["import type { SkillResult } from \"./result\";\nimport type {\n  SkillResource,\n  SkillResourceInfo,\n  SkillResourcePath\n} from \"./resource\";\nimport type { Skill, SkillName, SkillParseError } from \"./skill\";\n\n/**\n * Where skills are loaded from: a Computer Workspace, an R2 bucket, an\n * in-memory manifest, or a custom store.\n *\n * A source lists every skill it holds on each call, so changes show up the\n * next time a catalog is loaded. Expected failures are returned, not thrown.\n */\nexport interface SkillSource {\n  /** Stable identifier used in diagnostics and duplicate-name warnings. */\n  readonly id: string;\n  /**\n   * List the skills this source holds.\n   *\n   * @returns Valid skills and the skills that failed to parse, or\n   * `SkillSourceError` when the store could not be read.\n   */\n  list(): Promise<SkillResult<SkillListing, SkillSourceError>>;\n  /**\n   * Read one file bundled with a skill.\n   *\n   * @param skill - The skill that owns the file.\n   * @param path - Path relative to the skill directory.\n   */\n  readResource(\n    skill: SkillName,\n    path: SkillResourcePath\n  ): Promise<\n    SkillResult<SkillResource, SkillResourceNotFoundError | SkillSourceError>\n  >;\n}\n\n/** Everything a source found in one {@link SkillSource.list} call. */\nexport interface SkillListing {\n  /** Skills that parsed, in a stable order. */\n  readonly skills: readonly ListedSkill[];\n  /** Skills that did not follow the spec and were left out. */\n  readonly invalid: readonly InvalidSkill[];\n}\n\n/** A valid skill and the files bundled with it. */\nexport interface ListedSkill {\n  /** The parsed `SKILL.md`. */\n  readonly skill: Skill;\n  /** Files in the skill directory other than `SKILL.md`. */\n  readonly resources: readonly SkillResourceInfo[];\n  /**\n   * Absolute directory of the skill in the agent's filesystem, when the\n   * source stores skills there. Agents with a shell can run scripts from it.\n   */\n  readonly location?: string;\n  /**\n   * Spec rules the skill breaks but was loaded anyway, for example a name\n   * that does not match its directory, as the spec's guide for agents\n   * recommends.\n   */\n  readonly warnings?: readonly SkillParseError[];\n}\n\n/** A skill that failed to parse. */\nexport interface InvalidSkill {\n  /** Where the broken skill lives, such as `my-skill/SKILL.md`. */\n  readonly location: string;\n  /** Which spec rule it broke. */\n  readonly error: SkillParseError;\n}\n\n/** A source's backing store failed. */\nexport class SkillSourceError extends Error {\n  /** Stable tag for narrowing. */\n  readonly _tag = \"SkillSourceError\" as const;\n\n  /**\n   * @param sourceId - The source that failed.\n   * @param operation - What the source was doing.\n   * @param cause - The underlying store error.\n   */\n  constructor(\n    readonly sourceId: string,\n    readonly operation: \"list\" | \"read-resource\",\n    cause: unknown\n  ) {\n    super(\n      `Skill source \"${sourceId}\" failed to ${operation === \"list\" ? \"list skills\" : \"read a resource\"}: ${cause instanceof Error ? cause.message : String(cause)}`,\n      { cause }\n    );\n    this.name = \"SkillSourceError\";\n  }\n}\n\n/** A skill has no file at the requested path. */\nexport class SkillResourceNotFoundError extends Error {\n  /** Stable tag for narrowing. */\n  readonly _tag = \"SkillResourceNotFoundError\" as const;\n\n  /**\n   * @param skill - The skill that was searched.\n   * @param path - The missing path.\n   */\n  constructor(\n    readonly skill: SkillName,\n    readonly path: string\n  ) {\n    super(`Resource not found: ${skill}/${path}`);\n    this.name = \"SkillResourceNotFoundError\";\n  }\n}\n","import { err, ok, type SkillResult } from \"./result\";\nimport {\n  InvalidSkillResourcePathError,\n  parseSkillResourcePath,\n  type SkillResource,\n  type SkillResourceInfo\n} from \"./resource\";\nimport { isModelInvocable, type Skill, type SkillParseError } from \"./skill\";\nimport {\n  SkillResourceNotFoundError,\n  SkillSourceError,\n  type SkillListing,\n  type SkillSource\n} from \"./source\";\n\n/**\n * The skills an agent can use right now, merged from its sources.\n *\n * Load one with {@link loadSkillCatalog}; load it again to pick up changes.\n * Framework adapters (Think's AI SDK tools, the pi `skills()` extension)\n * wrap a catalog so every framework shows the model the same catalog text,\n * activation output, and resource output.\n */\nexport interface SkillCatalog {\n  /** Changes whenever {@link prompt} would change. */\n  readonly fingerprint: string;\n  /** Skills the model may activate, in source priority order. */\n  readonly skills: readonly SkillCatalogEntry[];\n  /** Problems found while loading: invalid skills, failed sources, duplicates. */\n  readonly diagnostics: readonly SkillDiagnostic[];\n  /**\n   * System-prompt text listing each skill's name and description.\n   *\n   * @returns The catalog prompt, or `null` when there are no skills.\n   */\n  prompt(): string | null;\n  /**\n   * Find a skill by name.\n   *\n   * @param name - Skill name.\n   * @returns The entry, or `undefined` when the catalog has no such skill.\n   */\n  find(name: string): SkillCatalogEntry | undefined;\n  /**\n   * Render a skill's instructions and resource list for the model.\n   *\n   * @param name - Skill name.\n   */\n  activate(name: string): SkillResult<string, UnknownSkillError>;\n  /**\n   * Read a bundled file.\n   *\n   * @param request - Either `name` and a skill-relative `path`, or a\n   * qualified `path` such as `my-skill/references/guide.md`.\n   */\n  readResource(request: {\n    readonly name?: string;\n    readonly path: string;\n  }): Promise<SkillResult<SkillCatalogResource, SkillResourceError>>;\n}\n\n/** A skill in a {@link SkillCatalog}. */\nexport interface SkillCatalogEntry {\n  /** The parsed skill. */\n  readonly skill: Skill;\n  /** Id of the source that provided it. */\n  readonly sourceId: string;\n  /** Files bundled with the skill. */\n  readonly resources: readonly SkillResourceInfo[];\n  /** Absolute directory in the agent's filesystem, when the source has one. */\n  readonly location?: string;\n}\n\n/** A resource read through a {@link SkillCatalog}. */\nexport interface SkillCatalogResource {\n  /** The skill that owns the resource. */\n  readonly entry: SkillCatalogEntry;\n  /** The resource and its content. */\n  readonly resource: SkillResource;\n}\n\n/** Why {@link SkillCatalog.readResource} failed. */\nexport type SkillResourceError =\n  | UnknownSkillError\n  | InvalidSkillResourcePathError\n  | SkillResourceNotFoundError\n  | SkillSourceError;\n\n/** A problem found while loading a catalog. Never fatal. */\nexport type SkillDiagnostic =\n  | {\n      /** A `SKILL.md` broke a spec rule and was skipped. */\n      readonly _tag: \"InvalidSkill\";\n      readonly sourceId: string;\n      readonly location: string;\n      readonly error: SkillParseError;\n    }\n  | {\n      /**\n       * A source could not be listed. With `previous`, its skills from the\n       * previous catalog are kept (`keptPrevious`); otherwise it is skipped.\n       */\n      readonly _tag: \"SourceFailed\";\n      readonly sourceId: string;\n      readonly error: SkillSourceError;\n      readonly keptPrevious: boolean;\n    }\n  | {\n      /** A skill breaks a spec rule but was loaded anyway. */\n      readonly _tag: \"SkillWarning\";\n      readonly sourceId: string;\n      readonly name: string;\n      readonly error: SkillParseError;\n    }\n  | {\n      /** A later source listed a name an earlier source already provided. */\n      readonly _tag: \"DuplicateSkill\";\n      readonly name: string;\n      readonly sourceId: string;\n      readonly keptSourceId: string;\n    };\n\n/** The catalog has no skill with the requested name. */\nexport class UnknownSkillError extends Error {\n  /** Stable tag for narrowing. */\n  readonly _tag = \"UnknownSkillError\" as const;\n\n  /** @param skill - The requested name. */\n  constructor(readonly skill: string) {\n    super(`Skill not found: ${skill}`);\n    this.name = \"UnknownSkillError\";\n  }\n}\n\n/** Options for {@link loadSkillCatalog}. */\nexport interface LoadSkillCatalogOptions {\n  /**\n   * The catalog this load replaces. When a source fails to list, its skills\n   * from `previous` are kept, so a transient outage does not remove working\n   * skills from the prompt and tools. Sources are matched by identity.\n   */\n  readonly previous?: SkillCatalog;\n}\n\n/**\n * Successful listings behind each catalog, by source object. Lets a later\n * load fall back to the last good listing of a failing source without\n * putting listings on the public catalog shape.\n */\nconst catalogListings = new WeakMap<\n  SkillCatalog,\n  ReadonlyMap<SkillSource, SkillListing>\n>();\n\n/**\n * Load every source and merge them into a catalog.\n *\n * Sources apply in order: the first source to list a name wins. A failing\n * source or an invalid skill becomes a diagnostic instead of an error, so\n * one bad source never hides the others. Skills that set\n * `disable-model-invocation: true` are left out.\n *\n * @param sources - Skill sources in priority order.\n * @param options - Pass `previous` to keep a failing source's last skills.\n * @returns The merged catalog.\n */\nexport async function loadSkillCatalog(\n  sources: readonly SkillSource[],\n  options: LoadSkillCatalogOptions = {}\n): Promise<SkillCatalog> {\n  const previousListings = options.previous\n    ? catalogListings.get(options.previous)\n    : undefined;\n  // Custom sources should return failures, but one that throws must still\n  // not hide the others.\n  const listings = await Promise.all(\n    sources.map(async (source) => ({\n      source,\n      listed: await source\n        .list()\n        .catch((cause: unknown) =>\n          err(new SkillSourceError(source.id, \"list\", cause))\n        )\n    }))\n  );\n\n  const diagnostics: SkillDiagnostic[] = [];\n  const entries = new Map<string, SkillCatalogEntry>();\n  // Resources are read from the source object that listed the skill, not\n  // looked up by id, because two sources may share an id.\n  const sourceBySkill = new Map<string, SkillSource>();\n  const goodListings = new Map<SkillSource, SkillListing>();\n\n  for (const { source, listed } of listings) {\n    let listing: SkillListing;\n    if (listed.ok) {\n      listing = listed.value;\n    } else {\n      const fallback = previousListings?.get(source);\n      diagnostics.push({\n        _tag: \"SourceFailed\",\n        sourceId: source.id,\n        error: listed.error,\n        keptPrevious: fallback !== undefined\n      });\n      if (!fallback) continue;\n      listing = fallback;\n    }\n    goodListings.set(source, listing);\n    for (const invalid of listing.invalid) {\n      diagnostics.push({\n        _tag: \"InvalidSkill\",\n        sourceId: source.id,\n        location: invalid.location,\n        error: invalid.error\n      });\n    }\n    for (const { skill, resources, location, warnings } of listing.skills) {\n      const existing = entries.get(skill.name);\n      if (existing) {\n        diagnostics.push({\n          _tag: \"DuplicateSkill\",\n          name: skill.name,\n          sourceId: source.id,\n          keptSourceId: existing.sourceId\n        });\n        continue;\n      }\n      entries.set(skill.name, {\n        skill,\n        sourceId: source.id,\n        resources,\n        ...(location === undefined ? {} : { location })\n      });\n      sourceBySkill.set(skill.name, source);\n      // Only for the copy the catalog keeps: a skipped duplicate already has\n      // its own diagnostic, and \"was loaded\" would be false for it.\n      for (const warning of warnings ?? []) {\n        diagnostics.push({\n          _tag: \"SkillWarning\",\n          sourceId: source.id,\n          name: skill.name,\n          error: warning\n        });\n      }\n    }\n  }\n\n  const skills = [...entries.values()].filter((entry) =>\n    isModelInvocable(entry.skill)\n  );\n  const visible = new Map<string, SkillCatalogEntry>(\n    skills.map((entry) => [entry.skill.name, entry])\n  );\n  const prompt = renderCatalogPrompt(skills);\n\n  const catalog: SkillCatalog = {\n    fingerprint: fingerprintOf(prompt ?? \"\"),\n    skills,\n    diagnostics,\n    prompt: () => prompt,\n    find: (name) => visible.get(name),\n    activate(name) {\n      const entry = visible.get(name);\n      return entry\n        ? ok(renderSkillActivation(entry))\n        : err(new UnknownSkillError(name));\n    },\n    async readResource(request) {\n      const target = resolveResourceTarget(visible, request);\n      if (!target.ok) return target;\n      const { entry, path } = target.value;\n      const source = sourceBySkill.get(entry.skill.name);\n      if (!source) return err(new UnknownSkillError(entry.skill.name));\n      const read = await source\n        .readResource(entry.skill.name, path)\n        .catch((cause: unknown) =>\n          err(new SkillSourceError(source.id, \"read-resource\", cause))\n        );\n      if (!read.ok) return read;\n      return ok({ entry, resource: read.value });\n    }\n  };\n  catalogListings.set(catalog, goodListings);\n  return catalog;\n}\n\n/**\n * Describe a diagnostic in one line, for logs.\n *\n * @param diagnostic - A diagnostic from {@link SkillCatalog.diagnostics}.\n */\nexport function formatSkillDiagnostic(diagnostic: SkillDiagnostic): string {\n  switch (diagnostic._tag) {\n    case \"InvalidSkill\":\n      return `Skipped invalid skill ${diagnostic.location} from source \"${diagnostic.sourceId}\": ${diagnostic.error.message}`;\n    case \"SkillWarning\":\n      return `Skill \"${diagnostic.name}\" from source \"${diagnostic.sourceId}\" breaks the Agent Skills spec but was loaded: ${diagnostic.error.message}`;\n    case \"SourceFailed\":\n      return `${diagnostic.error.message}. ${diagnostic.keptPrevious ? \"Its last listed skills were kept.\" : \"Its skills were skipped.\"}`;\n    case \"DuplicateSkill\":\n      return `Duplicate skill \"${diagnostic.name}\" from source \"${diagnostic.sourceId}\" ignored; already provided by \"${diagnostic.keptSourceId}\".`;\n  }\n}\n\n/**\n * Render a resource read for the model.\n *\n * @param read - A resource returned by {@link SkillCatalog.readResource}.\n */\nexport function renderSkillResource(read: SkillCatalogResource): string {\n  const { entry, resource } = read;\n  return [\n    `<skill_resource${attributes([\n      [\"name\", entry.skill.name],\n      [\"path\", resource.path],\n      [\"kind\", resource.kind],\n      [\"encoding\", resource.encoding],\n      [\"mimeType\", resource.mimeType]\n    ])}>`,\n    resource.content,\n    \"</skill_resource>\"\n  ].join(\"\\n\");\n}\n\nfunction renderCatalogPrompt(\n  skills: readonly SkillCatalogEntry[]\n): string | null {\n  if (skills.length === 0) return null;\n  return [\n    \"Available skills. When a task matches a skill, use activate_skill with its name before proceeding.\",\n    \"\",\n    ...skills.map(\n      ({ skill }) =>\n        `- ${skill.name}: ${skill.description.replace(/\\s+/g, \" \")}`\n    )\n  ].join(\"\\n\");\n}\n\nfunction renderSkillActivation(entry: SkillCatalogEntry): string {\n  const lines = [\n    `<skill_content${attributes([\n      [\"name\", entry.skill.name],\n      [\"location\", entry.location]\n    ])}>`,\n    entry.skill.body.trim()\n  ];\n  if (entry.resources.length > 0) {\n    lines.push(\"\", \"<skill_resources>\");\n    for (const resource of entry.resources) {\n      lines.push(\n        `  <file${attributes([\n          [\"kind\", resource.kind],\n          [\"encoding\", resource.encoding],\n          [\n            \"size\",\n            resource.size === undefined ? undefined : String(resource.size)\n          ]\n        ])}>${resource.path}</file>`\n      );\n    }\n    lines.push(\"</skill_resources>\");\n  }\n  lines.push(\"</skill_content>\");\n  return lines.join(\"\\n\");\n}\n\nfunction resolveResourceTarget(\n  skills: ReadonlyMap<string, SkillCatalogEntry>,\n  request: { readonly name?: string; readonly path: string }\n): SkillResult<\n  {\n    entry: SkillCatalogEntry;\n    path: SkillResourceInfo[\"path\"];\n  },\n  UnknownSkillError | InvalidSkillResourcePathError | SkillResourceNotFoundError\n> {\n  let name = request.name;\n  let relative = request.path;\n  if (name === undefined) {\n    const slash = relative.indexOf(\"/\");\n    if (slash <= 0) return err(new InvalidSkillResourcePathError(relative));\n    name = relative.slice(0, slash);\n    relative = relative.slice(slash + 1);\n  }\n  const entry = skills.get(name);\n  if (!entry) return err(new UnknownSkillError(name));\n  const path = parseSkillResourcePath(relative);\n  if (!path.ok) return path;\n  // Only files the source listed are readable, whatever the source's store\n  // holds beside them.\n  if (!entry.resources.some((resource) => resource.path === path.value)) {\n    return err(new SkillResourceNotFoundError(entry.skill.name, path.value));\n  }\n  return ok({ entry, path: path.value });\n}\n\nfunction attributes(\n  pairs: ReadonlyArray<readonly [string, string | undefined]>\n): string {\n  return pairs\n    .filter((pair): pair is readonly [string, string] => pair[1] !== undefined)\n    .map(([key, value]) => ` ${key}=\"${value.replace(/\"/g, \"&quot;\")}\"`)\n    .join(\"\");\n}\n\n/** Two FNV-1a passes with different seeds: cheap and stable across isolates. */\nfunction fingerprintOf(text: string): string {\n  let a = 0x811c9dc5;\n  let b = 0x01000193;\n  for (let index = 0; index < text.length; index++) {\n    const code = text.charCodeAt(index);\n    a = Math.imul(a ^ code, 0x01000193);\n    b = Math.imul(b ^ code, 0x811c9dc5);\n  }\n  return `${(a >>> 0).toString(16).padStart(8, \"0\")}${(b >>> 0).toString(16).padStart(8, \"0\")}`;\n}\n"],"mappings":"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"}

package/dist/catalog-BpiVV1OF.d.ts

@@ -0,0 +1,173 @@
+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

package/dist/chat/index.d.ts

@@ -9,7 +9,7 @@ import {
   _ as FiberRecoveryContext$1,
   at as isPositionlessAgentToolChunk,
   z as AgentToolEventState
-} from "../agent-routing-CDbpVjYq.js";
+} from "../agent-routing-vVMA7m8Y.js";
 import { _ as TaskStep, m as TaskRunOptions } from "../tasks-E89KdwkS.js";
 import {
   n as ClientToolSchema,
@@ -34,7 +34,7 @@ import {
   r as AgentToolProgressEmitResult,
   s as interceptAgentToolBroadcast,
   t as AgentToolBroadcastHooks
-} from "../agent-tools-C8DH8Yii.js";
+} from "../agent-tools-gGXXkf1z.js";
 import { l as SessionMessage } from "../types-B7LojTe4.js";
 import { ModelMessage, UIMessage } from "ai";
 import { Connection, FiberRecoveryContext } from "agents";

package/dist/chat-sdk/index.d.ts

@@ -1,8 +1,8 @@
 import {
-  bn as DynamicAgentClass,
   c as Agent,
-  xn as DynamicAgentStub
-} from "../agent-routing-CDbpVjYq.js";
+  nn as DynamicAgentStub,
+  tn as DynamicAgentClass
+} from "../agent-routing-vVMA7m8Y.js";
 import { Lock, QueueEntry, StateAdapter } from "chat";
 
 //#region src/chat-sdk/agent.d.ts

package/dist/chat-sdk/index.js

@@ -1,4 +1,4 @@
-import { i as getCurrentAgent, t as Agent } from "../src-DfLzdwlK.js";
+import { i as getCurrentAgent, t as Agent } from "../src-DoGNJ4Ud.js";
 //#region src/chat-sdk/agent.ts
 const NEXT_CLEANUP_AT_KEY = "next_cleanup_at";
 const CLEANUP_SCHEDULE_ID_KEY = "cleanup_schedule_id";