@anthropic-ai/sdk 0.120.0 → 0.122.0

package/src/resources/beta/skills/versions.ts

@@ -16,17 +16,17 @@ export class Versions extends APIResource {
    *
    * @example
    * ```ts
-   * const version = await client.beta.skills.versions.create(
-   *   'skill_id',
-   *   { files: [fs.createReadStream('path/to/file')] },
-   * );
+   * const betaSkillVersion =
+   *   await client.beta.skills.versions.create('skill_id', {
+   *     files: [fs.createReadStream('path/to/file')],
+   *   });
    * ```
    */
   create(
     skillID: string,
     params: VersionCreateParams,
     options?: RequestOptions,
-  ): APIPromise<VersionCreateResponse> {
+  ): APIPromise<BetaSkillVersion> {
     const { betas, ...body } = params;
     return this._client.post(
       path`/v1/skills/${skillID}/versions?beta=true`,
@@ -35,7 +35,7 @@ export class Versions extends APIResource {
           body,
           ...options,
           headers: buildHeaders([
-            { 'anthropic-beta': [...(betas ?? []), 'skills-2025-10-02'].toString() },
+            { ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined) },
             options?.headers,
           ]),
         },
@@ -50,22 +50,22 @@ export class Versions extends APIResource {
    *
    * @example
    * ```ts
-   * const version = await client.beta.skills.versions.retrieve(
-   *   'version',
-   *   { skill_id: 'skill_id' },
-   * );
+   * const betaSkillVersion =
+   *   await client.beta.skills.versions.retrieve('version', {
+   *     skill_id: 'skill_id',
+   *   });
    * ```
    */
   retrieve(
     version: string,
     params: VersionRetrieveParams,
     options?: RequestOptions,
-  ): APIPromise<VersionRetrieveResponse> {
+  ): APIPromise<BetaSkillVersion> {
     const { skill_id, betas } = params;
     return this._client.get(path`/v1/skills/${skill_id}/versions/${version}?beta=true`, {
       ...options,
       headers: buildHeaders([
-        { 'anthropic-beta': [...(betas ?? []), 'skills-2025-10-02'].toString() },
+        { ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined) },
         options?.headers,
       ]),
     });
@@ -77,7 +77,7 @@ export class Versions extends APIResource {
    * @example
    * ```ts
    * // Automatically fetches more pages as needed.
-   * for await (const versionListResponse of client.beta.skills.versions.list(
+   * for await (const betaSkillVersion of client.beta.skills.versions.list(
    *   'skill_id',
    * )) {
    *   // ...
@@ -88,16 +88,16 @@ export class Versions extends APIResource {
     skillID: string,
     params: VersionListParams | null | undefined = {},
     options?: RequestOptions,
-  ): PagePromise<VersionListResponsesPageCursor, VersionListResponse> {
+  ): PagePromise<BetaSkillVersionsPageCursor, BetaSkillVersion> {
     const { betas, ...query } = params ?? {};
     return this._client.getAPIList(
       path`/v1/skills/${skillID}/versions?beta=true`,
-      PageCursor<VersionListResponse>,
+      PageCursor<BetaSkillVersion>,
       {
         query,
         ...options,
         headers: buildHeaders([
-          { 'anthropic-beta': [...(betas ?? []), 'skills-2025-10-02'].toString() },
+          { ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined) },
           options?.headers,
         ]),
       },
@@ -109,22 +109,22 @@ export class Versions extends APIResource {
    *
    * @example
    * ```ts
-   * const version = await client.beta.skills.versions.delete(
-   *   'version',
-   *   { skill_id: 'skill_id' },
-   * );
+   * const betaDeletedSkillVersion =
+   *   await client.beta.skills.versions.delete('version', {
+   *     skill_id: 'skill_id',
+   *   });
    * ```
    */
   delete(
     version: string,
     params: VersionDeleteParams,
     options?: RequestOptions,
-  ): APIPromise<VersionDeleteResponse> {
+  ): APIPromise<BetaDeletedSkillVersion> {
     const { skill_id, betas } = params;
     return this._client.delete(path`/v1/skills/${skill_id}/versions/${version}?beta=true`, {
       ...options,
       headers: buildHeaders([
-        { 'anthropic-beta': [...(betas ?? []), 'skills-2025-10-02'].toString() },
+        { ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined) },
         options?.headers,
       ]),
     });
@@ -150,8 +150,8 @@ export class Versions extends APIResource {
       ...options,
       headers: buildHeaders([
         {
-          'anthropic-beta': [...(betas ?? []), 'skills-2025-10-02'].toString(),
           Accept: 'application/binary',
+          ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined),
         },
         options?.headers,
       ]),
@@ -160,72 +160,32 @@ export class Versions extends APIResource {
   }
 }
 
-export type VersionListResponsesPageCursor = PageCursor<VersionListResponse>;
+export type BetaSkillVersionsPageCursor = PageCursor<BetaSkillVersion>;
 
-export interface VersionCreateResponse {
+export interface BetaDeletedSkillVersion {
   /**
-   * Unique identifier for the skill version.
-   *
-   * The format and length of IDs may change over time.
+   * 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 version was created.
-   */
-  created_at: string;
-
-  /**
-   * Description of the skill version.
-   *
-   * This is extracted from the SKILL.md file in the skill upload.
-   */
-  description: string;
-
-  /**
-   * Directory name of the skill version.
-   *
-   * This is the top-level directory name that was extracted from the uploaded files.
-   */
-  directory: string;
-
-  /**
-   * Human-readable name of the skill version.
-   *
-   * This is extracted from the SKILL.md file in the skill upload.
-   */
-  name: string;
-
-  /**
-   * Identifier for the skill that this version belongs to.
-   */
-  skill_id: string;
-
-  /**
-   * Object type.
-   *
-   * For Skill Versions, this is always `"skill_version"`.
-   */
-  type: string;
-
-  /**
-   * Version identifier for the skill.
+   * Deleted object type.
    *
-   * Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
+   * For Skill Versions, this is always `"skill_version_deleted"`.
    */
-  version: string;
+  type: 'skill_version_deleted';
 }
 
-export interface VersionRetrieveResponse {
+export interface BetaSkillVersion {
   /**
-   * Unique identifier for the skill version.
-   *
-   * The format and length of IDs may change over time.
+   * 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 version was created.
+   * ISO 8601 timestamp of when the skill was created.
    */
   created_at: string;
 
@@ -237,76 +197,18 @@ export interface VersionRetrieveResponse {
   description: string;
 
   /**
-   * Directory name of the skill version.
-   *
-   * This is the top-level directory name that was extracted from the uploaded files.
-   */
-  directory: string;
-
-  /**
-   * Human-readable name of the skill version.
-   *
-   * This is extracted from the SKILL.md file in the skill upload.
+   * 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;
 
   /**
-   * Identifier for the skill that this version belongs to.
-   */
-  skill_id: string;
-
-  /**
-   * Object type.
-   *
-   * For Skill Versions, this is always `"skill_version"`.
-   */
-  type: string;
-
-  /**
-   * Version identifier for the skill.
-   *
-   * Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
-   */
-  version: string;
-}
-
-export interface VersionListResponse {
-  /**
-   * Unique identifier for the skill version.
+   * Unique identifier for the skill.
    *
    * The format and length of IDs may change over time.
    */
-  id: string;
-
-  /**
-   * ISO 8601 timestamp of when the skill version was created.
-   */
-  created_at: string;
-
-  /**
-   * Description of the skill version.
-   *
-   * This is extracted from the SKILL.md file in the skill upload.
-   */
-  description: string;
-
-  /**
-   * Directory name of the skill version.
-   *
-   * This is the top-level directory name that was extracted from the uploaded files.
-   */
-  directory: string;
-
-  /**
-   * Human-readable name of the skill version.
-   *
-   * This is extracted from the SKILL.md file in the skill upload.
-   */
-  name: string;
-
-  /**
-   * Identifier for the skill that this version belongs to.
-   */
   skill_id: string;
 
   /**
@@ -314,30 +216,7 @@ export interface VersionListResponse {
    *
    * For Skill Versions, this is always `"skill_version"`.
    */
-  type: string;
-
-  /**
-   * Version identifier for the skill.
-   *
-   * Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
-   */
-  version: string;
-}
-
-export interface VersionDeleteResponse {
-  /**
-   * Version identifier for the skill.
-   *
-   * Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
-   */
-  id: string;
-
-  /**
-   * Deleted object type.
-   *
-   * For Skill Versions, this is always `"skill_version_deleted"`.
-   */
-  type: string;
+  type: 'skill_version';
 }
 
 export interface VersionCreateParams {
@@ -406,11 +285,9 @@ export interface VersionDownloadParams {
 
 export declare namespace Versions {
   export {
-    type VersionCreateResponse as VersionCreateResponse,
-    type VersionRetrieveResponse as VersionRetrieveResponse,
-    type VersionListResponse as VersionListResponse,
-    type VersionDeleteResponse as VersionDeleteResponse,
-    type VersionListResponsesPageCursor as VersionListResponsesPageCursor,
+    type BetaDeletedSkillVersion as BetaDeletedSkillVersion,
+    type BetaSkillVersion as BetaSkillVersion,
+    type BetaSkillVersionsPageCursor as BetaSkillVersionsPageCursor,
     type VersionCreateParams as VersionCreateParams,
     type VersionRetrieveParams as VersionRetrieveParams,
     type VersionListParams as VersionListParams,

package/src/resources/beta/webhooks.ts

@@ -4,17 +4,27 @@ import { APIResource } from '../../core/resource';
 import { Webhook } from 'standardwebhooks';
 
 export class Webhooks extends APIResource {
-  unwrap(
-    body: string,
-    { headers, key }: { headers: Record<string, string>; key?: string },
-  ): UnwrapWebhookEvent {
-    if (headers !== undefined) {
-      const keyStr: string | null = key === undefined ? this._client.webhookKey : key;
-      if (keyStr === null) throw new Error('Webhook key must not be null in order to unwrap');
-      const wh = new Webhook(keyStr);
-      wh.verify(body, headers);
-    }
-    return JSON.parse(body) as UnwrapWebhookEvent;
+  /**
+   * Parses a webhook payload into an event without verifying its signature. Prefer
+   * `unwrap()` unless you have already verified the signature yourself.
+   */
+  parseUnverified(body: string): BetaWebhookEvent {
+    return JSON.parse(body) as BetaWebhookEvent;
+  }
+
+  /**
+   * Verifies the webhook signature from the `webhook-id`, `webhook-timestamp` and
+   * `webhook-signature` headers using your webhook signing key, then parses the
+   * payload into an event. Fails if the signature is missing or invalid.
+   */
+  unwrap(body: string, options: { headers: Record<string, string>; key?: string }): BetaWebhookEvent {
+    const headers = options?.headers;
+    if (headers == null) throw new Error('Webhook headers are required in order to verify the signature');
+    const keyStr: string | null = options.key === undefined ? this._client.webhookKey : options.key;
+    if (!keyStr) throw new Error('Webhook key must not be null or empty in order to unwrap');
+    const wh = new Webhook(keyStr);
+    wh.verify(body, headers);
+    return JSON.parse(body) as BetaWebhookEvent;
   }
 }
 
@@ -690,24 +700,10 @@ export interface BetaWebhookVaultDeletedEventData {
   workspace_id: string;
 }
 
-export interface UnwrapWebhookEvent {
-  /**
-   * Unique event identifier for idempotency.
-   */
-  id: string;
-
-  /**
-   * RFC 3339 timestamp when the event occurred.
-   */
-  created_at: string;
-
-  data: BetaWebhookEventData;
-
-  /**
-   * Object type. Always `event` for webhook payloads.
-   */
-  type: 'event';
-}
+/**
+ * @deprecated UnwrapWebhookEvent has been renamed to BetaWebhookEvent
+ */
+export type UnwrapWebhookEvent = BetaWebhookEvent;
 
 export declare namespace Webhooks {
   export {

package/src/tools/agent-toolset/node.browser.ts

@@ -96,10 +96,6 @@ export function setupSkills(_ctx: AgentToolContext): Promise<() => Promise<void>
   return nodeOnly('setupSkills');
 }
 
-export function resolveSkillVersion(_client: Anthropic, _skillId: string, _version: string): Promise<string> {
-  return nodeOnly('resolveSkillVersion');
-}
-
 export function extractSkillArchive(_resp: Response, _dest: string): Promise<void> {
   return nodeOnly('extractSkillArchive');
 }
@@ -127,7 +123,7 @@ export class BashTimeoutError extends AnthropicError {
 }
 
 export class BashSession {
-  constructor(_dir: string, _env?: NodeJS.ProcessEnv) {
+  constructor(_dir: string, _env?: Record<string, string | undefined>) {
     nodeOnly('BashSession');
   }
 

package/src/tools/agent-toolset/node.ts

@@ -52,7 +52,7 @@ import {
   isWithin,
 } from './fs-util';
 
-export { setupSkills, resolveSkillVersion, extractSkillArchive } from './skills';
+export { setupSkills, extractSkillArchive } from './skills';
 export {
   SessionMemoryStores,
   SessionMemoryError,
@@ -70,6 +70,8 @@ const BASH_DEFAULT_TIMEOUT_MS = 120_000;
 // memory) when AgentToolContext.maxFileBytes is unset. The reject-vs-truncate
 // behaviour remains a separate question pending CMA validation.
 const DEFAULT_MAX_FILE_BYTES = 256 * 1024;
+const READ_STREAM_CHUNK_BYTES = 64 * 1024;
+const NEWLINE = Buffer.from('\n');
 const GREP_OUTPUT_LIMIT = 100 * 1024;
 const GREP_MAX_LINE_LENGTH = 2000;
 const GLOB_RESULT_LIMIT = 200;
@@ -192,14 +194,16 @@ export interface AgentToolContext {
    * to the scrubbed process environment. To keep the defaults plus extra vars,
    * build the combined mapping yourself before passing it.
    */
-  env?: NodeJS.ProcessEnv;
+  env?: Record<string, string | undefined>;
   /**
-   * Size cap for the `read` and `edit` tools, which both load the whole file into
-   * memory. `undefined` (default) uses the built-in 256 KiB cap; a positive number
-   * sets a custom cap; `null` disables the cap entirely. Disabling it reintroduces
-   * the OOM risk on a model-controlled path, so pass `null` only when the sandbox
-   * can absorb arbitrarily large files. The non-regular-file (FIFO/device) guard
-   * always applies regardless of this value.
+   * Size cap for a whole-file `read` and for `edit`, which both load the whole
+   * file into memory. A `read` with `view_range` on a larger file streams it and
+   * applies the cap to the selected lines instead. `undefined` (default) uses the
+   * built-in 256 KiB cap; a positive number sets a custom cap; `null` disables the
+   * cap entirely. Disabling it reintroduces the OOM risk on a model-controlled
+   * path, so pass `null` only when the sandbox can absorb arbitrarily large files.
+   * The non-regular-file (FIFO/device) guard always applies regardless of this
+   * value.
    */
   maxFileBytes?: number | null;
 }
@@ -282,8 +286,8 @@ function readOnlyRootFor(ctx: AgentToolContext, target: string): Promise<string
  * environment verbatim; nothing here is merged in, so callers who want the
  * scrubbed process environment plus extras must build that mapping themselves.
  */
-function scrubbedShellEnv(): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = {};
+function scrubbedShellEnv(): Record<string, string | undefined> {
+  const env: Record<string, string | undefined> = {};
   for (const [key, value] of Object.entries(process.env)) {
     if (key.startsWith('ANTHROPIC_')) continue;
     env[key] = value;
@@ -304,7 +308,7 @@ export class BashSession {
   // in `#buf` (or once the shell dies). Event-driven: no polling loop.
   #waiting: { sentinel: string; resolve: () => void } | null = null;
 
-  constructor(dir: string, env: NodeJS.ProcessEnv = scrubbedShellEnv()) {
+  constructor(dir: string, env: Record<string, string | undefined> = scrubbedShellEnv()) {
     this.#proc = cp.spawn('/bin/bash', ['--noprofile', '--norc'], {
       cwd: dir,
       // `env` is the full base environment (the scrubbed process env by
@@ -525,6 +529,9 @@ export function betaReadTool(ctx: AgentToolContext): BetaRunnableTool {
     run: async ({ file_path, view_range }) => {
       if (!file_path) throw new ToolError('read: file_path is required');
       const abs = await resolvePath(ctx, file_path);
+      if (view_range?.length && view_range.length !== 2) {
+        throw new ToolError('read: view_range must be [start_line, end_line]');
+      }
       let data: string;
       try {
         // stat() before any open(): the size cap stops a multi-GB file from
@@ -536,10 +543,14 @@ export function betaReadTool(ctx: AgentToolContext): BetaRunnableTool {
         }
         const limit = resolveMaxBytes(ctx.maxFileBytes);
         if (limit !== null && st.size > limit) {
-          throw new ToolError(
-            `read: ${file_path} is ${st.size} bytes, exceeds ${limit}-byte limit. ` +
-              'Use bash (head/tail/sed) to read a slice.',
-          );
+          if (!view_range?.length) {
+            throw new ToolError(
+              `read: ${file_path} is ${st.size} bytes, exceeds ${limit}-byte limit. ` +
+                'Use the view_range parameter to read specific line ranges, e.g. view_range: [1, 500].',
+            );
+          }
+          const [startLine, endLine] = view_range as [number, number];
+          return await readRangeStreaming(abs, file_path, startLine, endLine, limit);
         }
         data = await fs.readFile(abs, 'utf8');
       } catch (e) {
@@ -547,7 +558,6 @@ export function betaReadTool(ctx: AgentToolContext): BetaRunnableTool {
         throw new ToolError(`read: ${fsErrorMessage(e, file_path)}`);
       }
       if (!view_range?.length) return data;
-      if (view_range.length !== 2) throw new ToolError('read: view_range must be [start_line, end_line]');
       const [startLine, endLine] = view_range as [number, number];
       const lines = data.split('\n');
       const start = Math.max(0, startLine - 1);
@@ -557,6 +567,101 @@ export function betaReadTool(ctx: AgentToolContext): BetaRunnableTool {
   });
 }
 
+/** Returns lines `[startLine, endLine]` of the file at `abs`, capping the selected bytes at `limit`. */
+async function readRangeStreaming(
+  abs: string,
+  filePath: string,
+  startLine: number,
+  endLine: number,
+  limit: number,
+): Promise<string> {
+  const lines = new LineRangeCollector(filePath, startLine, endLine, limit);
+  if (lines.rangeIsEmpty()) return '';
+  // Byte chunks rather than readline: a single huge line must never be buffered
+  // whole, so memory stays bounded by `limit` plus one chunk.
+  const stream = fssync.createReadStream(abs, { highWaterMark: READ_STREAM_CHUNK_BYTES });
+  try {
+    for await (const chunk of stream as AsyncIterable<Buffer>) {
+      lines.collectFrom(chunk);
+      if (lines.rangeIsCollected()) break;
+    }
+  } finally {
+    stream.destroy();
+  }
+  return lines.text();
+}
+
+/** Collects the bytes of lines `[startLine, endLine]` from consecutive file chunks, capped at `limit`. */
+class LineRangeCollector {
+  readonly #filePath: string;
+  readonly #startLine: number;
+  readonly #endLine: number;
+  readonly #start: number;
+  readonly #end: number;
+  readonly #limit: number;
+  #line = 0;
+  #collected: Buffer[] = [];
+  #collectedBytes = 0;
+
+  constructor(filePath: string, startLine: number, endLine: number, limit: number) {
+    this.#filePath = filePath;
+    this.#startLine = startLine;
+    this.#endLine = endLine;
+    this.#start = Math.max(0, startLine - 1);
+    this.#end = endLine > 0 ? endLine : Infinity;
+    this.#limit = limit;
+  }
+
+  rangeIsEmpty(): boolean {
+    return this.#end <= this.#start;
+  }
+
+  rangeIsCollected(): boolean {
+    return this.#line >= this.#end;
+  }
+
+  collectFrom(chunk: Buffer): void {
+    let lineStart = 0;
+    while (lineStart < chunk.length && !this.rangeIsCollected()) {
+      const newline = chunk.indexOf(0x0a, lineStart);
+      const lineEnd = newline < 0 ? chunk.length : newline;
+      if (this.#line >= this.#start) {
+        this.#collect(chunk.subarray(lineStart, lineEnd), newline >= 0);
+      }
+      if (newline < 0) break;
+      this.#line++;
+      lineStart = newline + 1;
+    }
+  }
+
+  #collect(lineBytes: Buffer, newlineTerminated: boolean): void {
+    this.#collected.push(lineBytes);
+    this.#collectedBytes += lineBytes.length;
+    if (newlineTerminated && this.#line + 1 < this.#end) {
+      this.#collected.push(NEWLINE);
+      this.#collectedBytes += NEWLINE.length;
+    }
+    if (this.#collectedBytes > this.#limit) throw this.#overLimitError();
+  }
+
+  #overLimitError(): ToolError {
+    if (this.#end - this.#start === 1) {
+      return new ToolError(
+        `read: line ${this.#start + 1} of ${this.#filePath} alone exceeds ${this.#limit}-byte limit. ` +
+          'The read tool cannot return part of a line, so view_range cannot narrow this further.',
+      );
+    }
+    return new ToolError(
+      `read: view_range [${this.#startLine}, ${this.#endLine}] of ${this.#filePath} exceeds ${this.#limit}-byte limit. ` +
+        'Narrow the view_range to read a smaller portion.',
+    );
+  }
+
+  text(): string {
+    return Buffer.concat(this.#collected, this.#collectedBytes).toString('utf8');
+  }
+}
+
 export function betaWriteTool(ctx: AgentToolContext): BetaRunnableTool {
   rejectUnrestrictedPaths(ctx.unrestrictedPaths);
   return betaTool({
@@ -624,7 +729,7 @@ export function betaEditTool(ctx: AgentToolContext): BetaRunnableTool {
         if (limit !== null && st.size > limit) {
           throw new ToolError(
             `edit: ${file_path} is ${st.size} bytes, exceeds ${limit}-byte limit. ` +
-              'Use bash (sed/awk) to edit a large file.',
+              'The edit tool loads the whole file and cannot modify a file this large.',
           );
         }
         data = await fs.readFile(abs, 'utf8');