@anthropic-ai/sdk 0.118.0 → 0.120.0

package/src/resources/skills/index.ts

@@ -0,0 +1,21 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Skills,
+  type DeletedSkill,
+  type Skill,
+  type SkillSource,
+  type SkillCreateParams,
+  type SkillListParams,
+  type SkillsPageCursor,
+} from './skills';
+export {
+  Versions,
+  type DeletedSkillVersion,
+  type SkillVersion,
+  type VersionCreateParams,
+  type VersionRetrieveParams,
+  type VersionListParams,
+  type VersionDeleteParams,
+  type SkillVersionsPageCursor,
+} from './versions';

package/src/resources/skills/skills.ts

@@ -0,0 +1,194 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as VersionsAPI from './versions';
+import {
+  DeletedSkillVersion,
+  SkillVersion,
+  SkillVersionsPageCursor,
+  VersionCreateParams,
+  VersionDeleteParams,
+  VersionListParams,
+  VersionRetrieveParams,
+  Versions,
+} from './versions';
+import { APIPromise } from '../../core/api-promise';
+import { PageCursor, type PageCursorParams, PagePromise } from '../../core/pagination';
+import { type Uploadable } from '../../core/uploads';
+import { RequestOptions } from '../../internal/request-options';
+import { multipartFormRequestOptions } from '../../internal/uploads';
+import { path } from '../../internal/utils/path';
+
+export class Skills extends APIResource {
+  versions: VersionsAPI.Versions = new VersionsAPI.Versions(this._client);
+
+  /**
+   * Create Skill
+   */
+  create(body: SkillCreateParams, options?: RequestOptions): APIPromise<Skill> {
+    return this._client.post(
+      '/v1/skills',
+      multipartFormRequestOptions({ body, ...options }, this._client, false),
+    );
+  }
+
+  /**
+   * Get Skill
+   */
+  retrieve(skillID: string, options?: RequestOptions): APIPromise<Skill> {
+    return this._client.get(path`/v1/skills/${skillID}`, options);
+  }
+
+  /**
+   * List Skills
+   */
+  list(
+    query: SkillListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<SkillsPageCursor, Skill> {
+    return this._client.getAPIList('/v1/skills', PageCursor<Skill>, { query, ...options });
+  }
+
+  /**
+   * Delete Skill
+   */
+  delete(skillID: string, options?: RequestOptions): APIPromise<DeletedSkill> {
+    return this._client.delete(path`/v1/skills/${skillID}`, options);
+  }
+}
+
+export type SkillsPageCursor = PageCursor<Skill>;
+
+export interface DeletedSkill {
+  /**
+   * Unique identifier for the skill.
+   *
+   * The format and length of IDs may change over time.
+   */
+  id: string;
+
+  /**
+   * Deleted object type.
+   *
+   * For Skills, this is always `"skill_deleted"`.
+   */
+  type: 'skill_deleted';
+}
+
+export interface Skill {
+  /**
+   * Unique identifier for the skill.
+   *
+   * The format and length of IDs may change over time.
+   */
+  id: string;
+
+  /**
+   * ISO 8601 timestamp of when the skill was created.
+   */
+  created_at: string;
+
+  /**
+   * Human-readable, single-line label for the Skill. Maximum 255 characters. Always
+   * set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not
+   * unique.
+   */
+  display_name: string;
+
+  /**
+   * ID of the newest Skill Version — what `latest` references resolve to. Always
+   * set: a Skill holds at least one version.
+   */
+  latest_version_id: string;
+
+  /**
+   * Where the Skill comes from.
+   *
+   * Possible values:
+   *
+   * - `"custom"`: authored by the platform user; private to their workspace
+   * - `"anthropic"`: published by Anthropic; shared and read-only
+   * - `"anthropic_example"`: Anthropic-published sample Skill
+   * - `"plugin"`: resolved from an installed plugin
+   */
+  source: SkillSource;
+
+  /**
+   * Object type.
+   *
+   * For Skills, this is always `"skill"`.
+   */
+  type: 'skill';
+
+  /**
+   * ISO 8601 timestamp of when the skill was last updated.
+   */
+  updated_at: string;
+}
+
+export interface SkillSource {
+  /**
+   * Where the Skill comes from.
+   *
+   * Possible values:
+   *
+   * - `"custom"`: authored by the platform user; private to their workspace
+   * - `"anthropic"`: published by Anthropic; shared and read-only
+   * - `"anthropic_example"`: Anthropic-published sample Skill
+   * - `"plugin"`: resolved from an installed plugin
+   */
+  type: 'custom' | 'anthropic' | 'anthropic_example' | 'plugin';
+}
+
+export interface SkillCreateParams {
+  /**
+   * Files to upload for the skill.
+   *
+   * All files must be in the same top-level directory and must include a SKILL.md
+   * file at the root of that directory.
+   */
+  files: Array<Uploadable>;
+
+  /**
+   * Human-readable, single-line label for the Skill. Maximum 255 characters. Always
+   * set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not
+   * unique.
+   */
+  display_name?: string | null;
+}
+
+export interface SkillListParams extends PageCursorParams {
+  /**
+   * Filter skills by source.
+   *
+   * If provided, only skills from the specified source will be returned:
+   *
+   * - `"custom"`: only return user-created skills
+   * - `"anthropic"`: only return Anthropic-created skills
+   */
+  source?: string | null;
+}
+
+Skills.Versions = Versions;
+
+export declare namespace Skills {
+  export {
+    type DeletedSkill as DeletedSkill,
+    type Skill as Skill,
+    type SkillSource as SkillSource,
+    type SkillsPageCursor as SkillsPageCursor,
+    type SkillCreateParams as SkillCreateParams,
+    type SkillListParams as SkillListParams,
+  };
+
+  export {
+    Versions as Versions,
+    type DeletedSkillVersion as DeletedSkillVersion,
+    type SkillVersion as SkillVersion,
+    type SkillVersionsPageCursor as SkillVersionsPageCursor,
+    type VersionCreateParams as VersionCreateParams,
+    type VersionRetrieveParams as VersionRetrieveParams,
+    type VersionListParams as VersionListParams,
+    type VersionDeleteParams as VersionDeleteParams,
+  };
+}

package/src/resources/skills/versions.ts

@@ -0,0 +1,160 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { PageCursor, type PageCursorParams, PagePromise } from '../../core/pagination';
+import { type Uploadable } from '../../core/uploads';
+import { RequestOptions } from '../../internal/request-options';
+import { multipartFormRequestOptions } from '../../internal/uploads';
+import { path } from '../../internal/utils/path';
+
+export class Versions extends APIResource {
+  /**
+   * Create Skill Version
+   */
+  create(skillID: string, body: VersionCreateParams, options?: RequestOptions): APIPromise<SkillVersion> {
+    return this._client.post(
+      path`/v1/skills/${skillID}/versions`,
+      multipartFormRequestOptions({ body, ...options }, this._client, false),
+    );
+  }
+
+  /**
+   * Get Skill Version
+   */
+  retrieve(
+    version: string,
+    params: VersionRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<SkillVersion> {
+    const { skill_id } = params;
+    return this._client.get(path`/v1/skills/${skill_id}/versions/${version}`, options);
+  }
+
+  /**
+   * List Skill Versions
+   */
+  list(
+    skillID: string,
+    query: VersionListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<SkillVersionsPageCursor, SkillVersion> {
+    return this._client.getAPIList(path`/v1/skills/${skillID}/versions`, PageCursor<SkillVersion>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Delete Skill Version
+   */
+  delete(
+    version: string,
+    params: VersionDeleteParams,
+    options?: RequestOptions,
+  ): APIPromise<DeletedSkillVersion> {
+    const { skill_id } = params;
+    return this._client.delete(path`/v1/skills/${skill_id}/versions/${version}`, options);
+  }
+}
+
+export type SkillVersionsPageCursor = PageCursor<SkillVersion>;
+
+export interface DeletedSkillVersion {
+  /**
+   * Unique identifier for this Skill Version. The id addresses the version in paths
+   * and pins it in references.
+   */
+  id: string;
+
+  /**
+   * Deleted object type.
+   *
+   * For Skill Versions, this is always `"skill_version_deleted"`.
+   */
+  type: 'skill_version_deleted';
+}
+
+export interface SkillVersion {
+  /**
+   * Unique identifier for this Skill Version. The id addresses the version in paths
+   * and pins it in references.
+   */
+  id: string;
+
+  /**
+   * ISO 8601 timestamp of when the skill was created.
+   */
+  created_at: string;
+
+  /**
+   * Description of the skill version.
+   *
+   * This is extracted from the SKILL.md file in the skill upload.
+   */
+  description: string;
+
+  /**
+   * The Skill's immutable kebab-case slug, set at creation from the first upload's
+   * SKILL.md frontmatter `name` (or its enclosing directory). Every later upload
+   * must resolve to the same value. Also the top-level directory of the Skill's
+   * mounted files and the base name of a downloaded archive.
+   */
+  name: string;
+
+  /**
+   * Unique identifier for the skill.
+   *
+   * The format and length of IDs may change over time.
+   */
+  skill_id: string;
+
+  /**
+   * Object type.
+   *
+   * For Skill Versions, this is always `"skill_version"`.
+   */
+  type: 'skill_version';
+}
+
+export interface VersionCreateParams {
+  /**
+   * Files to upload for the skill.
+   *
+   * All files must be in the same top-level directory and must include a SKILL.md
+   * file at the root of that directory.
+   */
+  files: Array<Uploadable>;
+}
+
+export interface VersionRetrieveParams {
+  /**
+   * Unique identifier for the skill.
+   *
+   * The format and length of IDs may change over time.
+   */
+  skill_id: string;
+}
+
+export interface VersionListParams extends PageCursorParams {}
+
+export interface VersionDeleteParams {
+  /**
+   * Unique identifier for the skill.
+   *
+   * The format and length of IDs may change over time.
+   */
+  skill_id: string;
+}
+
+export declare namespace Versions {
+  export {
+    type DeletedSkillVersion as DeletedSkillVersion,
+    type SkillVersion as SkillVersion,
+    type SkillVersionsPageCursor as SkillVersionsPageCursor,
+    type VersionCreateParams as VersionCreateParams,
+    type VersionRetrieveParams as VersionRetrieveParams,
+    type VersionListParams as VersionListParams,
+    type VersionDeleteParams as VersionDeleteParams,
+  };
+}

package/src/resources/skills.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './skills/index';

package/src/tools/agent-toolset/fs-util.ts

@@ -15,13 +15,25 @@ export const DIR_CREATE_MODE = 0o755;
 /** Mode for files the file tools create. */
 export const FILE_CREATE_MODE = 0o644;
 
-/** `realpath` `p`, or return `p` unchanged when it cannot be resolved. */
-async function realpathOrSelf(p: string): Promise<string> {
-  try {
-    return await fs.realpath(p);
-  } catch {
-    return p;
+/** True when `p` is `root` itself or lexically contained within it. */
+export function isWithin(root: string, p: string): boolean {
+  const rel = path.relative(root, p);
+  return rel === '' || (!rel.startsWith('..' + path.sep) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+/**
+ * The first entry of `roots` whose canonical form contains the
+ * already-canonical `target`, returned as configured; `undefined` when none
+ * does. Each root goes through {@link canonicalize} at check time, exactly like
+ * the workdir in {@link confineToRoot}, so granting access (`allowedRoots`)
+ * and refusing writes (`readOnlyRoots`) can never resolve the same entry two
+ * different ways.
+ */
+export async function containingRoot(roots: readonly string[], target: string): Promise<string | undefined> {
+  for (const root of roots) {
+    if (isWithin(await canonicalize(path.resolve(root)), target)) return root;
   }
+  return undefined;
 }
 
 /** Matches Linux MAXSYMLINKS, the threshold at which `realpath` itself reports ELOOP. */
@@ -79,17 +91,19 @@ export async function canonicalize(abs: string): Promise<string> {
 }
 
 /**
- * Resolve `p` and confine it to `root`.
+ * Resolve `p` against `root` and confine it to `root` or one of `allowedRoots`
+ * (absolute paths, resolved at check time exactly like `root`).
  *
  * Absolute and relative inputs go through the same canonicalise-then-contain
- * check — an absolute path that lands inside `root` is permitted, only paths
- * that resolve *outside* are rejected. Every symlink in `p` (including the
- * leaf, even a dangling one) is resolved before the confinement check, and the
- * resolved path is what the caller then operates on, so a symlink inside `root`
- * that points outside it can neither pass the check nor be followed afterwards.
- * `..` is collapsed lexically before any symlink is followed. A path that cannot
- * be resolved (symlink loop, unreadable component) is rejected with a
- * `ToolError` naming `p`, never the host's absolute path.
+ * check — an absolute path that lands inside a permitted root is accepted,
+ * only paths that resolve *outside* all of them are rejected. Every symlink in
+ * `p` (including the leaf, even a dangling one) is resolved before the
+ * confinement check, and the resolved path is what the caller then operates
+ * on, so a symlink inside `root` that points outside it can neither pass the
+ * check nor be followed afterwards. `..` is collapsed lexically before any
+ * symlink is followed. A path that cannot be resolved (symlink loop, unreadable
+ * component) is rejected with a `ToolError` naming `p`, never the host's
+ * absolute path.
  *
  * Residual TOCTOU: a component could still be swapped for a symlink between this
  * call and the eventual `fs` operation. Closing that fully needs per-component
@@ -99,22 +113,24 @@ export async function canonicalize(abs: string): Promise<string> {
 export async function confineToRoot(
   root: string,
   p: string,
-  opts?: { allowOutside?: boolean },
+  opts?: { allowedRoots?: readonly string[] },
 ): Promise<string> {
-  const allowOutside = opts?.allowOutside ?? false;
-  const realRoot = await realpathOrSelf(path.resolve(root));
-  const abs = path.resolve(realRoot, p);
-  if (allowOutside) return abs;
+  const allowedRoots = opts?.allowedRoots ?? [];
+  const realRoot = await canonicalize(path.resolve(root));
   let real: string;
   try {
-    real = await canonicalize(abs);
+    real = await canonicalize(path.resolve(realRoot, p));
   } catch (err) {
     throw new ToolError(fsErrorMessage(err, `path ${JSON.stringify(p)}`));
   }
-  if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
-    throw new ToolError(`path ${JSON.stringify(p)} escapes workdir`);
+  if (isWithin(realRoot, real) || (await containingRoot(allowedRoots, real)) !== undefined) {
+    return real;
   }
-  return real;
+  const permitted =
+    allowedRoots.length ?
+      "the session's working directory and its other permitted directories"
+    : "the session's working directory";
+  throw new ToolError(`path ${JSON.stringify(p)} is outside ${permitted}`);
 }
 
 /**