agents 0.31.0 → 0.32.0

package/dist/serializable.d.ts

@@ -1,4 +1,4 @@
-import { k as StreamingResponse } from "./agent-routing-wS1TimZ_.js";
+import { k as StreamingResponse } from "./agent-routing-vVMA7m8Y.js";
 
 //#region src/serializable.d.ts
 type SerializablePrimitive = undefined | null | string | number | boolean;

package/dist/skill-DRBcIBjC.d.ts

@@ -0,0 +1,221 @@
+//#region src/skills/result.d.ts
+/**
+ * The outcome of a skills operation that can fail in an expected way.
+ *
+ * Skill parsing and source I/O return failures as values instead of throwing,
+ * so a broken `SKILL.md` or an unreachable bucket never takes down the agent.
+ *
+ * @template T - The success value.
+ * @template E - The expected error.
+ */
+type SkillResult<T, E extends Error> =
+  | {
+      readonly ok: true;
+      readonly value: T;
+    }
+  | {
+      readonly ok: false;
+      readonly error: E;
+    };
+//#endregion
+//#region src/skills/resource.d.ts
+declare const skillResourcePathBrand: unique symbol;
+/**
+ * A normalized path to a file inside a skill directory, relative to the
+ * skill root (for example `references/style-guide.md`). Construct one with
+ * {@link parseSkillResourcePath}.
+ */
+type SkillResourcePath = string & {
+  readonly [skillResourcePathBrand]: true;
+};
+/**
+ * What a skill file is for, from the spec's directory conventions:
+ * `scripts/`, `references/`, and `assets/`. Anything else is a `file`.
+ */
+type SkillResourceKind = "script" | "reference" | "asset" | "file";
+/** A file bundled with a skill, without its content. */
+interface SkillResourceInfo {
+  /** Path relative to the skill directory. */
+  readonly path: SkillResourcePath;
+  /** Role inferred from the top-level directory. */
+  readonly kind: SkillResourceKind;
+  /** How {@link SkillResource.content} is encoded. */
+  readonly encoding: "text" | "base64";
+  /** MIME type, when the extension maps to a known one. */
+  readonly mimeType?: string;
+  /** Size in bytes, when the source knows it without reading the file. */
+  readonly size?: number;
+}
+/** A file bundled with a skill, with its content. */
+interface SkillResource extends SkillResourceInfo {
+  /** UTF-8 text, or base64 for binary files. */
+  readonly content: string;
+}
+/** A resource path that is absolute, escapes the skill, or is malformed. */
+declare class InvalidSkillResourcePathError extends Error {
+  readonly path: string;
+  /** Stable tag for narrowing. */
+  readonly _tag: "InvalidSkillResourcePathError";
+  /** @param path - The rejected path. */
+  constructor(path: string);
+}
+/**
+ * Parse a path to a file inside a skill directory.
+ *
+ * @param path - Candidate path relative to the skill root.
+ * @returns The branded path, or `InvalidSkillResourcePathError` when it is
+ * empty, absolute, contains `.`/`..`/empty segments or NUL, or names
+ * `SKILL.md` itself.
+ */
+declare function parseSkillResourcePath(
+  path: string
+): SkillResult<SkillResourcePath, InvalidSkillResourcePathError>;
+//#endregion
+//#region src/skills/skill.d.ts
+/**
+ * The Agent Skills `Skill` type and its frontmatter rules. `SKILL.md`
+ * text parsing lives in `./markdown` so code that only handles parsed
+ * skills does not load the YAML parser.
+ *
+ * The rules come from https://agentskills.io/specification, applied the way
+ * the spec's guide for agents recommends
+ * (https://agentskills.io/client-implementation/adding-skills-support):
+ * a skill that breaks a rule still loads, and each broken rule is returned
+ * as a warning. Only a skill that cannot be used is rejected: no
+ * description, no usable name, or frontmatter that is not YAML.
+ *
+ * A skill that follows the spec parses with no warnings, so authoring tools
+ * check `warnings.length === 0` before storing a skill.
+ *
+ * Frontmatter keys the spec does not define are kept in
+ * {@link Skill.extraFields}.
+ *
+ * @module
+ */
+declare const skillNameBrand: unique symbol;
+/**
+ * A skill name the parser accepted. It is always a single safe path segment
+ * (no `/`, `\`, NUL, or control characters, and not `.` or `..`), so it can
+ * name a directory, a tool enum value, and a qualified resource path. A name
+ * from {@link parseSkillName}, or from a parse with no warnings, also follows
+ * the spec format.
+ */
+type SkillName = string & {
+  readonly [skillNameBrand]: true;
+};
+/** Why a `SKILL.md` or skill field broke a rule. */
+type SkillParseErrorCode =
+  | "missing-frontmatter"
+  | "invalid-yaml"
+  | "invalid-frontmatter"
+  | "invalid-name"
+  | "name-mismatch"
+  | "invalid-description"
+  | "invalid-license"
+  | "invalid-compatibility"
+  | "invalid-metadata"
+  | "invalid-allowed-tools";
+/**
+ * A `SKILL.md` that breaks an Agent Skills rule. Returned as the error of a
+ * failed parse, or as a warning when the skill loads anyway.
+ */
+declare class SkillParseError extends Error {
+  readonly code: SkillParseErrorCode;
+  /** Stable tag for narrowing. */
+  readonly _tag: "SkillParseError";
+  /**
+   * @param code - Which rule the skill broke.
+   * @param message - Human-readable explanation, safe to show to a model.
+   * @param options - The underlying cause, such as a YAML syntax error.
+   */
+  constructor(
+    code: SkillParseErrorCode,
+    message: string,
+    options?: {
+      cause?: unknown;
+    }
+  );
+}
+/** A parsed Agent Skill: its frontmatter and Markdown instructions. */
+interface Skill {
+  /** The skill's name. */
+  readonly name: SkillName;
+  /** What the skill does and when to use it. */
+  readonly description: string;
+  /** License name or a reference to a bundled license file. */
+  readonly license?: string;
+  /** Environment requirements. */
+  readonly compatibility?: string;
+  /** String key-value metadata. Empty when the skill declares none. */
+  readonly metadata: Readonly<Record<string, string>>;
+  /** Pre-approved tools from `allowed-tools`. Experimental in the spec. */
+  readonly allowedTools: readonly string[];
+  /** Frontmatter keys the spec does not define, kept verbatim. */
+  readonly extraFields: Readonly<Record<string, unknown>>;
+  /** Markdown instructions after the frontmatter. */
+  readonly body: string;
+}
+/** Options for {@link parseSkill}. */
+interface ParseSkillOptions {
+  /**
+   * Name of the directory that holds this `SKILL.md`. The spec requires the
+   * skill's `name` to match it; a mismatch is a warning. A missing `name`
+   * falls back to the directory, with a warning.
+   */
+  readonly directory?: string;
+}
+/** The outcome of parsing a skill. */
+type SkillParseResult =
+  | {
+      readonly ok: true /** The parsed skill. */;
+      readonly value: Skill;
+      /**
+       * Spec rules the skill breaks but was loaded anyway. Empty for a
+       * skill that follows the spec.
+       */
+      readonly warnings: readonly SkillParseError[];
+    }
+  | {
+      readonly ok: false;
+      readonly error: SkillParseError;
+    };
+/**
+ * Parse a skill name against the Agent Skills spec.
+ *
+ * The name is NFKC-normalized first. It must be 1-64 characters of
+ * lowercase letters, digits, and hyphens, must not start or end with a
+ * hyphen, and must not contain `--`.
+ *
+ * @param input - The candidate name.
+ * @returns The branded name, or `SkillParseError` with code `invalid-name`.
+ */
+declare function parseSkillName(
+  input: string
+): SkillResult<SkillName, SkillParseError>;
+/**
+ * Whether a model may activate this skill on its own. Skills opt out with
+ * `disable-model-invocation: true`, as a top-level field or in `metadata`.
+ *
+ * @param skill - The parsed skill.
+ * @returns `false` when the skill disables model invocation.
+ */
+declare function isModelInvocable(skill: Skill): boolean;
+//#endregion
+export {
+  SkillParseErrorCode as a,
+  parseSkillName as c,
+  SkillResourceInfo as d,
+  SkillResourceKind as f,
+  SkillResult as h,
+  SkillParseError as i,
+  InvalidSkillResourcePathError as l,
+  parseSkillResourcePath as m,
+  Skill as n,
+  SkillParseResult as o,
+  SkillResourcePath as p,
+  SkillName as r,
+  isModelInvocable as s,
+  ParseSkillOptions as t,
+  SkillResource as u
+};
+//# sourceMappingURL=skill-DRBcIBjC.d.ts.map

package/dist/skills/index.d.ts

@@ -1,52 +1,291 @@
 import {
-  C as parseSkillFrontmatter,
-  S as SkillSource,
-  _ as SkillResourceDescriptor,
-  a as SkillWorkspaceSeedOptions,
-  b as SkillScriptRequest,
-  c as r2,
-  d as SkillDescriptor,
-  f as SkillManifest,
-  g as SkillResource,
-  h as SkillRegistrySnapshot,
-  i as SkillWorkspace,
-  l as fromManifest,
-  m as SkillManifestResource,
-  n as WorkerSkillScriptRunnerOptions,
-  o as SkillWorkspaceSeedResult,
-  p as SkillManifestEntry,
-  r as runner,
-  s as R2SkillSourceOptions,
-  t as SkillRegistry,
-  u as SkillContent,
-  v as SkillRunContext,
-  w as parseSkillMarkdown,
-  x as SkillScriptRunner,
-  y as SkillScriptContext
-} from "../index-iv9FTXX9.js";
+  a as SkillParseErrorCode,
+  c as parseSkillName,
+  d as SkillResourceInfo,
+  f as SkillResourceKind,
+  h as SkillResult,
+  i as SkillParseError,
+  l as InvalidSkillResourcePathError,
+  m as parseSkillResourcePath,
+  n as Skill,
+  o as SkillParseResult,
+  p as SkillResourcePath,
+  r as SkillName,
+  s as isModelInvocable,
+  t as ParseSkillOptions,
+  u as SkillResource
+} from "../skill-DRBcIBjC.js";
+import {
+  a as SkillSource,
+  i as SkillResourceNotFoundError,
+  n as ListedSkill,
+  o as SkillSourceError,
+  r as SkillListing,
+  t as InvalidSkill
+} from "../source-9RQzlEhM.js";
+import {
+  a as SkillDiagnostic,
+  c as formatSkillDiagnostic,
+  i as SkillCatalogResource,
+  l as loadSkillCatalog,
+  n as SkillCatalog,
+  o as SkillResourceError,
+  r as SkillCatalogEntry,
+  s as UnknownSkillError,
+  t as LoadSkillCatalogOptions,
+  u as renderSkillResource
+} from "../catalog-BpiVV1OF.js";
+import {
+  a as SkillScriptRunner,
+  i as SkillScriptRequest,
+  n as SkillScriptContext,
+  r as SkillScriptFile,
+  t as SkillRunContext
+} from "../script-CFDLTk5b.js";
+import { t as SkillScriptWorkspace } from "../script-workspace-BpdAYq1R.js";
+
+//#region src/skills/markdown.d.ts
+/**
+ * Parse a `SKILL.md` file.
+ *
+ * Follows the spec's guide for agents: a skill that breaks a rule still
+ * parses, with each broken rule in `warnings`. Frontmatter that only fails
+ * because of unquoted values containing `: ` (for example
+ * `description: Use when: the user asks`), which many clients accept, is
+ * read again with those values quoted. The parse fails only when the skill
+ * cannot be used: no frontmatter, YAML that still does not parse, no
+ * description, or an unsafe name.
+ *
+ * To check a skill before storing it, require `warnings` to be empty.
+ *
+ * @param markdown - The full file: YAML frontmatter, then Markdown.
+ * @param options - `directory` to check the name against.
+ * @returns The parsed skill and warnings, or a `SkillParseError`.
+ */
+declare function parseSkill(
+  markdown: string,
+  options?: ParseSkillOptions
+): SkillParseResult;
+/**
+ * Render a skill back to `SKILL.md` text.
+ *
+ * @param skill - The parsed skill.
+ * @returns Frontmatter and body that {@link parseSkill} reads back to an
+ * equal skill.
+ */
+declare function formatSkill(skill: Skill): string;
+//#endregion
+//#region src/skills/workspace.d.ts
+/**
+ * The parts of a `@cloudflare/computer` Workspace a skill source reads. A
+ * local `Workspace`, a client from `getWorkspace()`, and Think's
+ * `this.workspace` all fit.
+ */
+interface SkillWorkspace {
+  /** The Workspace filesystem. */
+  readonly fs: {
+    /** Walk a directory tree. */ find(
+      directory: string,
+      pattern?: string,
+      options?: {
+        exclude?: string[];
+      }
+    ): Promise<
+      ReadonlyArray<{
+        path: string;
+        type: string;
+      }>
+    > /** Read a file's bytes. */;
+    readFile(path: string): Promise<ReadableStream<Uint8Array>>;
+  };
+}
+/** Options for {@link workspace}. */
+interface WorkspaceSkillSourceOptions {
+  /**
+   * Absolute directory that holds the skill directories. Defaults to
+   * `/workspace/.agents/skills`, the cross-client Agent Skills location.
+   */
+  readonly root?: string;
+  /** Source id for diagnostics. Defaults to `workspace:<root>`. */
+  readonly id?: string;
+}
+/** Default skills directory inside a Workspace. */
+declare const DEFAULT_WORKSPACE_SKILLS_ROOT = "/workspace/.agents/skills";
+/**
+ * Create a source that reads skills from a Computer Workspace.
+ *
+ * Skills are plain files: every `<root>/<skill-name>/SKILL.md` is a skill,
+ * and the files beside it are its resources. The Workspace is read on every
+ * listing, so skills the agent or a user adds, edits, or deletes take effect
+ * the next time the catalog loads. A missing root lists no skills.
+ *
+ * @param target - The Workspace to read.
+ * @param options - Skills root and source id.
+ * @returns A source backed by the Workspace.
+ * @throws TypeError when `root` is not a normalized absolute path.
+ */
+declare function workspace(
+  target: SkillWorkspace,
+  options?: WorkspaceSkillSourceOptions
+): SkillSource;
+//#endregion
+//#region src/skills/r2.d.ts
+/** Options for {@link r2}. */
+interface R2SkillSourceOptions {
+  /** Key prefix that holds the skill directories, such as `skills/`. */
+  readonly prefix?: string;
+  /** Source id for diagnostics. Defaults to `r2:<prefix>`. */
+  readonly id?: string;
+  /** Only serve these skill names. Serves every skill when omitted. */
+  readonly skills?: readonly string[];
+  /**
+   * How long a bucket listing is reused before the bucket is listed again.
+   * Defaults to 60 seconds; `0` lists on every call.
+   */
+  readonly refreshIntervalMs?: number;
+}
+/**
+ * Create a read-only source backed by an R2 bucket.
+ *
+ * The bucket holds the Agent Skills layout under `prefix`:
+ * `<prefix><skill-name>/SKILL.md`, plus any bundled files beside it.
+ *
+ * @param bucket - The R2 binding.
+ * @param options - Prefix, id, name allowlist, and listing cache interval.
+ * @returns A source that reads skills from the bucket.
+ */
+declare function r2(
+  bucket: R2Bucket,
+  options?: R2SkillSourceOptions
+): SkillSource;
+//#endregion
+//#region src/skills/manifest.d.ts
+/** Skills defined in code, for tests and small fixed sets. */
+interface SkillManifest {
+  /** Source id used in diagnostics. */
+  readonly id: string;
+  /** The skills, in priority order. */
+  readonly skills: readonly SkillManifestEntry[];
+  /**
+   * @deprecated Ignored. Catalogs fingerprint the prompt they render, so
+   * sources no longer carry a fingerprint.
+   */
+  readonly fingerprint?: string;
+}
+/** One skill in a {@link SkillManifest}, written as `SKILL.md` fields. */
+interface SkillManifestEntry {
+  /** Spec-valid skill name. */
+  readonly name: string;
+  /** What the skill does and when to use it. */
+  readonly description: string;
+  /** Markdown instructions. */
+  readonly body: string;
+  /** License name or bundled license file. */
+  readonly license?: string;
+  /** Environment requirements. */
+  readonly compatibility?: string;
+  /**
+   * String key-value metadata. Scalar values are converted to strings, as
+   * in `SKILL.md`; nested values make the entry invalid.
+   */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /** Space-separated pre-approved tools. */
+  readonly allowedTools?: string;
+  /** Files bundled with the skill. */
+  readonly resources?: readonly SkillManifestResource[];
+  /** @deprecated Ignored. */
+  readonly version?: string;
+  /** @deprecated Ignored; the entry fields define the skill. */
+  readonly rawContent?: string;
+}
+/** A file in a {@link SkillManifestEntry}. */
+interface SkillManifestResource {
+  /** Path relative to the skill directory. */
+  readonly path: string;
+  /** UTF-8 text, or base64 when `encoding` is `"base64"`. */
+  readonly content: string;
+  /** Overrides the encoding inferred from the file extension. */
+  readonly encoding?: "text" | "base64";
+  /** Overrides the MIME type inferred from the file extension. */
+  readonly mimeType?: string;
+  /** Overrides the kind inferred from the top-level directory. */
+  readonly kind?: SkillResourceKind;
+  /** @deprecated Ignored; the size is the content's length. */
+  readonly size?: number;
+  /** @deprecated Ignored; scripts are always run as stored. */
+  readonly precompiled?: boolean;
+}
+/**
+ * Create a source from skills defined in code.
+ *
+ * Entries pass the same checks as `SKILL.md` files from other sources:
+ * broken spec rules become warnings, and entries without a usable
+ * name or description are reported as invalid. Useful for tests and for small fixed skill sets
+ * that do not need a Workspace or bucket.
+ *
+ * @param definition - The skills to serve.
+ * @returns A source that always lists the same skills.
+ */
+declare function manifest(definition: SkillManifest): SkillSource;
+/**
+ * Create a source from skills defined in code.
+ *
+ * @deprecated Use {@link manifest}.
+ * @param definition - The skills to serve.
+ * @returns A source that always lists the same skills.
+ */
+declare const fromManifest: typeof manifest;
+//#endregion
 export {
+  DEFAULT_WORKSPACE_SKILLS_ROOT,
+  type InvalidSkill,
+  InvalidSkillResourcePathError,
+  type ListedSkill,
+  type LoadSkillCatalogOptions,
+  type ParseSkillOptions,
   type R2SkillSourceOptions,
-  type SkillContent,
-  type SkillDescriptor,
+  type Skill,
+  type SkillCatalog,
+  type SkillCatalogEntry,
+  type SkillCatalogResource,
+  type SkillDiagnostic,
+  type SkillListing,
   type SkillManifest,
   type SkillManifestEntry,
   type SkillManifestResource,
-  SkillRegistry,
-  type SkillRegistrySnapshot,
+  type SkillName,
+  SkillParseError,
+  type SkillParseErrorCode,
+  type SkillParseResult,
   type SkillResource,
-  type SkillResourceDescriptor,
+  type SkillResourceError,
+  type SkillResourceInfo,
+  type SkillResourceKind,
+  SkillResourceNotFoundError,
+  type SkillResourcePath,
+  type SkillResult,
   type SkillRunContext,
   type SkillScriptContext,
+  type SkillScriptFile,
   type SkillScriptRequest,
   type SkillScriptRunner,
+  type SkillScriptWorkspace,
   type SkillSource,
+  SkillSourceError,
   type SkillWorkspace,
-  type SkillWorkspaceSeedOptions,
-  type SkillWorkspaceSeedResult,
-  type WorkerSkillScriptRunnerOptions,
+  UnknownSkillError,
+  type WorkspaceSkillSourceOptions,
+  formatSkill,
+  formatSkillDiagnostic,
   fromManifest,
-  parseSkillFrontmatter,
-  parseSkillMarkdown,
+  isModelInvocable,
+  loadSkillCatalog,
+  manifest,
+  parseSkill,
+  parseSkillName,
+  parseSkillResourcePath,
   r2,
-  runner
+  renderSkillResource,
+  workspace
 };
+//# sourceMappingURL=index.d.ts.map