@anthropic-ai/sdk 0.119.0 → 0.120.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.120.0 (2026-08-19)
+
+Full Changelog: [sdk-v0.119.0...sdk-v0.120.0](https://github.com/anthropics/anthropic-sdk-typescript/compare/sdk-v0.119.0...sdk-v0.120.0)
+
+### Features
+
+* **api:** managed agents web search config and self hosted sandbox memory ([ba8ec50](https://github.com/anthropics/anthropic-sdk-typescript/commit/ba8ec50ffe31e10781971a942d54289439307424))
+
+
+### Chores
+
+* **internal:** use a single pnpm workspace lockfile ([#359](https://github.com/anthropics/anthropic-sdk-typescript/issues/359)) ([3c32145](https://github.com/anthropics/anthropic-sdk-typescript/commit/3c32145d2bc4d53888c6c6857c9af216eec95fb9))
+
 ## 0.119.0 (2026-08-19)
 
 Full Changelog: [sdk-v0.118.0...sdk-v0.119.0](https://github.com/anthropics/anthropic-sdk-typescript/compare/sdk-v0.118.0...sdk-v0.119.0)

package/helpers/beta/environments.d.mts

@@ -9,10 +9,11 @@
  * - {@link EnvironmentWorker} (`client.beta.environments.work.worker`) — the full
  *   composition: poll → set up the workdir + skills → run a
  *   {@link SessionToolRunner} while heartbeating the work-item lease →
- *   force-stop on exit → loop. Use `handleItem()` for the per-item flow when you
- *   already hold a claimed work item — with no arguments it reads the
- *   `ANTHROPIC_*` env vars that `ant worker poll --on-work` sets. The class is
- *   also exported here if you prefer `new EnvironmentWorker({ client, ... })`.
+ *   force-stop on exit (unless the lease was lost to another holder) → loop.
+ *   Use `handleItem()` for the per-item flow when you already hold a claimed
+ *   work item — with no arguments it reads the `ANTHROPIC_*` env vars that
+ *   `ant worker poll --on-work` sets. The class is also exported here if you
+ *   prefer `new EnvironmentWorker({ client, ... })`.
  *
  * The tool implementations themselves (`betaAgentToolset20260401` and the
  * per-tool factories) live in their own Node-only module — import them directly

package/helpers/beta/environments.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"environments.d.mts","sourceRoot":"","sources":["../../src/helpers/beta/environments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,GAC9B,yCAAqC"}
+{"version":3,"file":"environments.d.mts","sourceRoot":"","sources":["../../src/helpers/beta/environments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,GAC9B,yCAAqC"}

package/helpers/beta/environments.d.ts

@@ -9,10 +9,11 @@
  * - {@link EnvironmentWorker} (`client.beta.environments.work.worker`) — the full
  *   composition: poll → set up the workdir + skills → run a
  *   {@link SessionToolRunner} while heartbeating the work-item lease →
- *   force-stop on exit → loop. Use `handleItem()` for the per-item flow when you
- *   already hold a claimed work item — with no arguments it reads the
- *   `ANTHROPIC_*` env vars that `ant worker poll --on-work` sets. The class is
- *   also exported here if you prefer `new EnvironmentWorker({ client, ... })`.
+ *   force-stop on exit (unless the lease was lost to another holder) → loop.
+ *   Use `handleItem()` for the per-item flow when you already hold a claimed
+ *   work item — with no arguments it reads the `ANTHROPIC_*` env vars that
+ *   `ant worker poll --on-work` sets. The class is also exported here if you
+ *   prefer `new EnvironmentWorker({ client, ... })`.
  *
  * The tool implementations themselves (`betaAgentToolset20260401` and the
  * per-tool factories) live in their own Node-only module — import them directly

package/helpers/beta/environments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environments.d.ts","sourceRoot":"","sources":["../../src/helpers/beta/environments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,GAC9B,wCAAqC"}
+{"version":3,"file":"environments.d.ts","sourceRoot":"","sources":["../../src/helpers/beta/environments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,GAC9B,wCAAqC"}

package/helpers/beta/environments.js

@@ -12,10 +12,11 @@ exports.DEFAULT_MAX_IDLE_MS = exports.MANAGED_AGENTS_BETA = exports.SessionToolR
  * - {@link EnvironmentWorker} (`client.beta.environments.work.worker`) — the full
  *   composition: poll → set up the workdir + skills → run a
  *   {@link SessionToolRunner} while heartbeating the work-item lease →
- *   force-stop on exit → loop. Use `handleItem()` for the per-item flow when you
- *   already hold a claimed work item — with no arguments it reads the
- *   `ANTHROPIC_*` env vars that `ant worker poll --on-work` sets. The class is
- *   also exported here if you prefer `new EnvironmentWorker({ client, ... })`.
+ *   force-stop on exit (unless the lease was lost to another holder) → loop.
+ *   Use `handleItem()` for the per-item flow when you already hold a claimed
+ *   work item — with no arguments it reads the `ANTHROPIC_*` env vars that
+ *   `ant worker poll --on-work` sets. The class is also exported here if you
+ *   prefer `new EnvironmentWorker({ client, ... })`.
  *
  * The tool implementations themselves (`betaAgentToolset20260401` and the
  * per-tool factories) live in their own Node-only module — import them directly

package/helpers/beta/environments.js.map

@@ -1 +1 @@
-{"version":3,"file":"environments.js","sourceRoot":"","sources":["../../src/helpers/beta/environments.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,yDAYsC;AAXpC,mGAAA,UAAU,OAAA;AACV,0GAAA,iBAAiB,OAAA;AACjB,0GAAA,iBAAiB,OAAA;AACjB,4GAAA,mBAAmB,OAAA;AACnB,4GAAA,mBAAmB,OAAA"}
+{"version":3,"file":"environments.js","sourceRoot":"","sources":["../../src/helpers/beta/environments.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,yDAYsC;AAXpC,mGAAA,UAAU,OAAA;AACV,0GAAA,iBAAiB,OAAA;AACjB,0GAAA,iBAAiB,OAAA;AACjB,4GAAA,mBAAmB,OAAA;AACnB,4GAAA,mBAAmB,OAAA"}

package/helpers/beta/environments.mjs

@@ -9,10 +9,11 @@
  * - {@link EnvironmentWorker} (`client.beta.environments.work.worker`) — the full
  *   composition: poll → set up the workdir + skills → run a
  *   {@link SessionToolRunner} while heartbeating the work-item lease →
- *   force-stop on exit → loop. Use `handleItem()` for the per-item flow when you
- *   already hold a claimed work item — with no arguments it reads the
- *   `ANTHROPIC_*` env vars that `ant worker poll --on-work` sets. The class is
- *   also exported here if you prefer `new EnvironmentWorker({ client, ... })`.
+ *   force-stop on exit (unless the lease was lost to another holder) → loop.
+ *   Use `handleItem()` for the per-item flow when you already hold a claimed
+ *   work item — with no arguments it reads the `ANTHROPIC_*` env vars that
+ *   `ant worker poll --on-work` sets. The class is also exported here if you
+ *   prefer `new EnvironmentWorker({ client, ... })`.
  *
  * The tool implementations themselves (`betaAgentToolset20260401` and the
  * per-tool factories) live in their own Node-only module — import them directly

package/helpers/beta/environments.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"environments.mjs","sourceRoot":"","sources":["../../src/helpers/beta/environments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,GAOpB,yCAAqC"}
+{"version":3,"file":"environments.mjs","sourceRoot":"","sources":["../../src/helpers/beta/environments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,GAOpB,yCAAqC"}

package/internal/file-store.d.mts

@@ -0,0 +1,136 @@
+/**
+ * `FileStore` — one confined folder; a relative path cannot escape it.
+ *
+ * Beta scope: symlinks are refused or skipped wherever the store meets them,
+ * but there is no hardening against a process racing the store's own
+ * syscalls; fsync durability, non-POSIX hosts, and read-size caps are out of
+ * scope.
+ */
+/** A refused operation — input the store will not act on. OS errors propagate with their `.code`. */
+export declare class FileStoreError extends Error {
+    static readonly ESCAPES_ROOT = "escapes the store root";
+    static readonly IS_A_SYMLINK = "is a symlink";
+    static readonly NOT_A_FILE = "is not a regular file";
+    static readonly NOT_A_DIRECTORY = "is not a directory";
+    static readonly NOT_UTF8 = "is not valid utf-8";
+    static readonly MOVE_DESTINATION_EXISTS = "already exists";
+    readonly reason: string;
+    readonly relPath: string;
+    constructor(reason: string, relPath: string);
+}
+/**
+ * The store's resolved root, and what {@link FileStore.dispose} will do to it.
+ *
+ * `removedOnDispose` is true when `open` found no root, so `dispose` removes
+ * it. A root that was already there is someone else's — a pre-seeded mount, a
+ * caller's workdir — and is kept.
+ */
+export type Root = {
+    path: string;
+    removedOnDispose: boolean;
+};
+/** Options for {@link FileStore.open} / {@link openFileStore}. */
+export interface OpenFileStoreOptions {
+    /**
+     * Restrict the store to valid UTF-8 (default `false`): a `put` of binary
+     * bytes and a `get` of a binary file are refused with
+     * {@link FileStoreError}, so a caller that decodes what `get` returns can
+     * never hit a decode error.
+     */
+    utf8?: boolean;
+}
+/** Resolve `root`; creates nothing — only {@link FileStore.createRoot} makes the folder. */
+export declare function openFileStore(root: string, opts?: OpenFileStoreOptions): Promise<FileStore>;
+/**
+ * True for a path usable verbatim as a store location: absolute, with no `..`
+ * components. Paths are judged in POSIX terms — they are wire values naming
+ * locations inside a POSIX container, not host-native paths.
+ */
+export declare function isPathLegal(p: string): boolean;
+/**
+ * One confined folder of regular files.
+ *
+ * Every `relPath` is relative to the root (a leading `/` also means the root)
+ * and refused with {@link FileStoreError} when it escapes. The store holds
+ * regular files only: symlinks are refused on read and skipped by listings —
+ * {@link findSymlinks} reports them. A `relPath` resolving to the root itself
+ * is banned by this interface: `put` and `get` refuse it, `move` and `remove`
+ * do nothing. A store opened with `utf8: true` refuses binary content the
+ * same way — on `put` of such bytes and on `get` of such a file. Only
+ * {@link createRoot} makes the root: writes create directories below it,
+ * never the root itself, so a root removed while the store is open stays
+ * removed and the write fails with `ENOENT`.
+ */
+export declare class FileStore {
+    private readonly rootPath;
+    /** True ⇒ this open created the root, so {@link dispose} removes it. */
+    private readonly removedOnDispose;
+    /** Set iff the store refuses non-UTF-8 content; {@link requireUtf8} decodes against it, on both put and get. */
+    private readonly decoder;
+    /** `hashtree`'s advisory cache; every hit re-validates against a fresh stat. */
+    private readonly hashes;
+    static isPathLegal: typeof isPathLegal;
+    /** @internal — use {@link FileStore.open} / {@link openFileStore}. */
+    constructor(root: string, removedOnDispose: boolean, utf8Only?: boolean);
+    /** Resolve `root`; creates nothing — only {@link createRoot} makes the folder. */
+    static open(root: string, opts?: OpenFileStoreOptions): Promise<FileStore>;
+    /** Create the root directory and any missing ancestors; already existing is fine. */
+    createRoot(): Promise<void>;
+    /** The resolved root, and what {@link dispose} will do to it. */
+    root(): Root;
+    /**
+     * Remove the root iff `open` created it; pre-existing roots are kept.
+     *
+     * Wired to `Symbol.asyncDispose` at runtime when the host provides it, so
+     * `await using` works on engines with explicit resource management.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Write `data` (`string` UTF-8 or bytes) atomically to the file at `relPath`.
+     *
+     * Missing directories below the root are created; a missing root is not —
+     * the write fails with `ENOENT`.
+     */
+    put(relPath: string, data: string | Uint8Array, opts?: {
+        executable?: boolean;
+    }): Promise<void>;
+    /** The file's bytes; `null` when absent. */
+    get(relPath: string): Promise<Uint8Array | null>;
+    /** The relative path of every file under the directory `under`. */
+    ls(under?: string): Promise<Set<string>>;
+    /**
+     * Every symlink under `under` — listings skip them and reads refuse them,
+     * so a caller that must know they exist asks here.
+     */
+    findSymlinks(under?: string): Promise<Set<string>>;
+    /**
+     * `{relPath: sha256Hex}` of every file under the directory `under`.
+     *
+     * Unchanged files — same size, mtime, and ctime since the last call —
+     * reuse their recorded hash instead of being re-read.
+     */
+    hashtree(under?: string): Promise<Record<string, string>>;
+    /** One file's sha256; `null` when absent. Shares {@link hashtree}'s cache. */
+    hashFile(relPath: string): Promise<string | null>;
+    /**
+     * Rename `src` to `dst`; an existing `dst` is refused. The banned store
+     * root as either end does nothing.
+     */
+    move(src: string, dst: string): Promise<void>;
+    /** Delete a file or subtree; absent — and the banned store root — do nothing. */
+    remove(relPath: string): Promise<void>;
+    private resolveUnderRoot;
+    private requireUtf8;
+    private hashViaCache;
+}
+/** sha256 of a file's contents, streamed — constant memory on any file size. */
+declare function hashFile(full: string): Promise<string>;
+/** Test seam — the hasher, the trust margin, and the walk clock. @internal */
+export declare const _internals: {
+    hashFile: typeof hashFile;
+    timestampTrustMarginNs: bigint;
+    nowNs: () => bigint;
+};
+export declare const LocalFileStore: typeof FileStore;
+export {};
+//# sourceMappingURL=file-store.d.mts.map

package/internal/file-store.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.d.mts","sourceRoot":"","sources":["../src/internal/file-store.ts"],"names":[],"mappings":"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"}

package/internal/file-store.d.ts

@@ -0,0 +1,136 @@
+/**
+ * `FileStore` — one confined folder; a relative path cannot escape it.
+ *
+ * Beta scope: symlinks are refused or skipped wherever the store meets them,
+ * but there is no hardening against a process racing the store's own
+ * syscalls; fsync durability, non-POSIX hosts, and read-size caps are out of
+ * scope.
+ */
+/** A refused operation — input the store will not act on. OS errors propagate with their `.code`. */
+export declare class FileStoreError extends Error {
+    static readonly ESCAPES_ROOT = "escapes the store root";
+    static readonly IS_A_SYMLINK = "is a symlink";
+    static readonly NOT_A_FILE = "is not a regular file";
+    static readonly NOT_A_DIRECTORY = "is not a directory";
+    static readonly NOT_UTF8 = "is not valid utf-8";
+    static readonly MOVE_DESTINATION_EXISTS = "already exists";
+    readonly reason: string;
+    readonly relPath: string;
+    constructor(reason: string, relPath: string);
+}
+/**
+ * The store's resolved root, and what {@link FileStore.dispose} will do to it.
+ *
+ * `removedOnDispose` is true when `open` found no root, so `dispose` removes
+ * it. A root that was already there is someone else's — a pre-seeded mount, a
+ * caller's workdir — and is kept.
+ */
+export type Root = {
+    path: string;
+    removedOnDispose: boolean;
+};
+/** Options for {@link FileStore.open} / {@link openFileStore}. */
+export interface OpenFileStoreOptions {
+    /**
+     * Restrict the store to valid UTF-8 (default `false`): a `put` of binary
+     * bytes and a `get` of a binary file are refused with
+     * {@link FileStoreError}, so a caller that decodes what `get` returns can
+     * never hit a decode error.
+     */
+    utf8?: boolean;
+}
+/** Resolve `root`; creates nothing — only {@link FileStore.createRoot} makes the folder. */
+export declare function openFileStore(root: string, opts?: OpenFileStoreOptions): Promise<FileStore>;
+/**
+ * True for a path usable verbatim as a store location: absolute, with no `..`
+ * components. Paths are judged in POSIX terms — they are wire values naming
+ * locations inside a POSIX container, not host-native paths.
+ */
+export declare function isPathLegal(p: string): boolean;
+/**
+ * One confined folder of regular files.
+ *
+ * Every `relPath` is relative to the root (a leading `/` also means the root)
+ * and refused with {@link FileStoreError} when it escapes. The store holds
+ * regular files only: symlinks are refused on read and skipped by listings —
+ * {@link findSymlinks} reports them. A `relPath` resolving to the root itself
+ * is banned by this interface: `put` and `get` refuse it, `move` and `remove`
+ * do nothing. A store opened with `utf8: true` refuses binary content the
+ * same way — on `put` of such bytes and on `get` of such a file. Only
+ * {@link createRoot} makes the root: writes create directories below it,
+ * never the root itself, so a root removed while the store is open stays
+ * removed and the write fails with `ENOENT`.
+ */
+export declare class FileStore {
+    private readonly rootPath;
+    /** True ⇒ this open created the root, so {@link dispose} removes it. */
+    private readonly removedOnDispose;
+    /** Set iff the store refuses non-UTF-8 content; {@link requireUtf8} decodes against it, on both put and get. */
+    private readonly decoder;
+    /** `hashtree`'s advisory cache; every hit re-validates against a fresh stat. */
+    private readonly hashes;
+    static isPathLegal: typeof isPathLegal;
+    /** @internal — use {@link FileStore.open} / {@link openFileStore}. */
+    constructor(root: string, removedOnDispose: boolean, utf8Only?: boolean);
+    /** Resolve `root`; creates nothing — only {@link createRoot} makes the folder. */
+    static open(root: string, opts?: OpenFileStoreOptions): Promise<FileStore>;
+    /** Create the root directory and any missing ancestors; already existing is fine. */
+    createRoot(): Promise<void>;
+    /** The resolved root, and what {@link dispose} will do to it. */
+    root(): Root;
+    /**
+     * Remove the root iff `open` created it; pre-existing roots are kept.
+     *
+     * Wired to `Symbol.asyncDispose` at runtime when the host provides it, so
+     * `await using` works on engines with explicit resource management.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Write `data` (`string` UTF-8 or bytes) atomically to the file at `relPath`.
+     *
+     * Missing directories below the root are created; a missing root is not —
+     * the write fails with `ENOENT`.
+     */
+    put(relPath: string, data: string | Uint8Array, opts?: {
+        executable?: boolean;
+    }): Promise<void>;
+    /** The file's bytes; `null` when absent. */
+    get(relPath: string): Promise<Uint8Array | null>;
+    /** The relative path of every file under the directory `under`. */
+    ls(under?: string): Promise<Set<string>>;
+    /**
+     * Every symlink under `under` — listings skip them and reads refuse them,
+     * so a caller that must know they exist asks here.
+     */
+    findSymlinks(under?: string): Promise<Set<string>>;
+    /**
+     * `{relPath: sha256Hex}` of every file under the directory `under`.
+     *
+     * Unchanged files — same size, mtime, and ctime since the last call —
+     * reuse their recorded hash instead of being re-read.
+     */
+    hashtree(under?: string): Promise<Record<string, string>>;
+    /** One file's sha256; `null` when absent. Shares {@link hashtree}'s cache. */
+    hashFile(relPath: string): Promise<string | null>;
+    /**
+     * Rename `src` to `dst`; an existing `dst` is refused. The banned store
+     * root as either end does nothing.
+     */
+    move(src: string, dst: string): Promise<void>;
+    /** Delete a file or subtree; absent — and the banned store root — do nothing. */
+    remove(relPath: string): Promise<void>;
+    private resolveUnderRoot;
+    private requireUtf8;
+    private hashViaCache;
+}
+/** sha256 of a file's contents, streamed — constant memory on any file size. */
+declare function hashFile(full: string): Promise<string>;
+/** Test seam — the hasher, the trust margin, and the walk clock. @internal */
+export declare const _internals: {
+    hashFile: typeof hashFile;
+    timestampTrustMarginNs: bigint;
+    nowNs: () => bigint;
+};
+export declare const LocalFileStore: typeof FileStore;
+export {};
+//# sourceMappingURL=file-store.d.ts.map

package/internal/file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../src/internal/file-store.ts"],"names":[],"mappings":"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"}