@anthropic-ai/sdk 0.119.0 → 0.121.0

package/lib/environments/worker.d.ts

@@ -1,7 +1,7 @@
 import type { Anthropic } from "../../client.js";
 import type { BetaRunnableTool } from "../tools/BetaRunnableTool.js";
 import type { BetaToolRunnerRequestOptions } from "../tools/BetaToolRunner.js";
-import type { AgentToolContext } from "../../tools/agent-toolset/node.js";
+import type { AgentToolContext, MemoryDeleteMode } from "../../tools/agent-toolset/node.js";
 /**
  * Either a fixed tool array or a factory invoked once per claimed session with
  * that session's {@link AgentToolContext} — use the factory form to bind
@@ -17,10 +17,11 @@ export interface EnvironmentWorkerOptions {
      */
     environmentId?: string;
     /**
-     * The environment key — the single credential for the runner. It authenticates
-     * the work-poll calls and every per-session call (event stream, lease
-     * heartbeat, force-stop). Required by {@link EnvironmentWorker.run}; falls back
-     * to `ANTHROPIC_ENVIRONMENT_KEY` in {@link EnvironmentWorker.handleItem}.
+     * The environment key — the worker's standing credential: polling always
+     * uses it, and per-session calls fall back to it when a claimed item's
+     * `secret` doesn't yield a sessions token. Required by
+     * {@link EnvironmentWorker.run}; falls back to `ANTHROPIC_ENVIRONMENT_KEY` in
+     * {@link EnvironmentWorker.handleItem}.
      */
     environmentKey?: string;
     /**
@@ -35,12 +36,41 @@ export interface EnvironmentWorkerOptions {
     tools?: EnvironmentWorkerTools;
     /** Base directory for the per-session {@link AgentToolContext}. Defaults to `process.cwd()`. */
     workdir?: string;
-    /** Forwarded to the per-session {@link AgentToolContext}. */
+    /**
+     * @deprecated No longer accepted: the file tools are always confined to
+     * `workdir` plus `allowedRoots`, which is neither behavior this flag used to
+     * select, so passing either value throws. Remove it; list extra directories
+     * in {@link AgentToolContext.allowedRoots}. The property is removed in a
+     * future release.
+     */
     unrestrictedPaths?: boolean;
     /** Forwarded to the per-session {@link AgentToolContext} (`maxFileBytes`). */
     maxFileBytes?: number | null;
     /** Forwarded to {@link SessionToolRunner} (`maxIdleMs`). */
     maxIdleMs?: number;
+    /**
+     * How often (milliseconds) to sync the session's attached memory stores back
+     * while it runs — checked after each dispatched tool call, plus one final
+     * sync when the session ends cleanly. Defaults to
+     * `DEFAULT_MEMORY_SYNC_INTERVAL_MS` (15s); the constructor throws for
+     * values below `MIN_MEMORY_SYNC_INTERVAL_MS` (5s). Every teardown also runs
+     * a push-only flush of changed files; that flush and the final sync are
+     * each bounded by `MEMORY_FLUSH_TIMEOUT_MS`, and a warning is logged when
+     * either bound cuts work off. `null` disables memory download and sync
+     * entirely. Memory stores are only touched for work items whose `secret`
+     * carries a `sessions_token`; while sync is enabled, an item without one
+     * fails when its session has memory stores attached, because those stores
+     * cannot be mounted without the token. With `null` the same item runs,
+     * without memory, and nothing is logged — turning sync off is the
+     * operator's explicit choice.
+     */
+    memorySyncIntervalMs?: number | null;
+    /**
+     * Whether local file deletions may delete on the server — see
+     * {@link MemoryDeleteMode}. Uploads and pulls are unaffected.
+     * Defaults to `"enabled"`.
+     */
+    memorySyncDeletions?: MemoryDeleteMode;
     /** Forwarded to the {@link WorkPoller}. */
     workerId?: string;
     /** External abort signal; aborting it ends the run. */
@@ -74,9 +104,30 @@ export interface HandleItemOptions {
      * `ANTHROPIC_ENVIRONMENT_KEY`.
      */
     environmentKey?: string;
+    /**
+     * The work item's per-item `secret` payload from the poll response. Falls
+     * back to `ANTHROPIC_WORK_SECRET`. Unlike the others it is optional — when
+     * present, the sessions token extracted from it is preferred as the Bearer
+     * credential for this item's heartbeat / force-stop / skill-download /
+     * session calls; when absent (or undecodable) those calls use the
+     * environment key.
+     */
+    workSecret?: string;
     /** External abort signal; aborting it ends the run. Defaults to the constructor's signal. */
     signal?: AbortSignal;
 }
+/**
+ * Extract the per-item sessions token from a work item's `secret` payload.
+ *
+ * The `secret` the poll response populates is not itself a credential: it is a
+ * URL-safe base64 JSON payload matching {@link BetaWorkSecret} — the
+ * `sessions_token` (the bearer for this item's work lifecycle and
+ * session-level calls) plus fields this worker does not consume. Returns the
+ * sessions token, or `null` (meaning: fall back to the environment key) when
+ * the payload is missing, doesn't decode, or carries no token. Never log the
+ * payload or anything extracted from it.
+ */
+export declare function sessionsTokenFromSecret(secret: string | null | undefined): string | null;
 /**
  * The self-hosted environment runner, composed from the control-plane
  * {@link WorkPoller} and the per-session {@link SessionToolRunner}.
@@ -85,9 +136,17 @@ export interface HandleItemOptions {
  * {@link AgentToolContext}, downloads the session agent's skills
  * (`setupSkills`), then runs a {@link SessionToolRunner} for the session
  * while heartbeating the work-item lease on the same event loop; on exit it
- * force-stops the work item, cleans up the downloaded skills, and loops to the
- * next one. The lease heartbeat reports `state === "stopping"` / a lost lease
- * back into the run by aborting the session runner.
+ * force-stops the work item (unless the lease was lost, in which case the item
+ * is left to whoever holds it now), cleans up the downloaded skills, and loops
+ * to the next one. The lease heartbeat reports `state === "stopping"` / a lost
+ * lease back into the run by aborting the session runner.
+ *
+ * The `environmentKey` is the worker's standing credential. When a claimed
+ * work item carries a per-item `secret` (a short-lived payload the poll
+ * response may populate), the sessions token extracted from it is preferred
+ * over the environment key for that item's heartbeat / force-stop /
+ * skill-download / session calls; polling itself always uses the environment
+ * key, and items without a usable secret fall back to it entirely.
  *
  * Use {@link EnvironmentWorker.handleItem} if you already hold a claimed work
  * item (e.g. a `worker poll --on-work` script handed one to a fresh process) and
@@ -115,12 +174,19 @@ export declare class EnvironmentWorker {
     readonly environmentKey: string | undefined;
     readonly tools: EnvironmentWorkerTools | undefined;
     readonly workdir: string;
+    /** @deprecated Never set; see {@link EnvironmentWorkerOptions.unrestrictedPaths}. */
     readonly unrestrictedPaths: boolean | undefined;
     readonly maxFileBytes: number | null | undefined;
     readonly maxIdleMs: number | undefined;
+    readonly memorySyncIntervalMs: number | null | undefined;
+    readonly memorySyncDeletions: MemoryDeleteMode;
     readonly workerId: string | undefined;
     readonly requestOptions: BetaToolRunnerRequestOptions | undefined;
-    constructor(opts: EnvironmentWorkerOptions);
+    constructor(opts: Omit<EnvironmentWorkerOptions, 'unrestrictedPaths'>);
+    /** @deprecated `unrestrictedPaths` is no longer accepted — see {@link EnvironmentWorkerOptions.unrestrictedPaths}. */
+    constructor(opts: Omit<EnvironmentWorkerOptions, 'unrestrictedPaths'> & {
+        unrestrictedPaths: boolean;
+    });
     /**
      * Poll the environment and service each claimed session until the supplied
      * signal (or the one passed to the constructor) aborts. Throws if
@@ -133,7 +199,9 @@ export declare class EnvironmentWorker {
      * download the session agent's skills (`setupSkills`), run a
      * {@link SessionToolRunner} for the session while heartbeating the work-item
      * lease, and force-stop the work item on exit (whether the runner finishes
-     * normally, throws, or the heartbeat loop signals shutdown).
+     * normally, throws, or the control plane signals shutdown). The one
+     * exception is a lost lease: the item then belongs to the queue or another
+     * worker and is left alone.
      *
      * Use this when something else does the claiming — e.g. a `worker poll
      * --on-work` script that hands an already-claimed item to a fresh process. The
@@ -143,7 +211,16 @@ export declare class EnvironmentWorker {
      * option, then the worker's own `environmentKey`, then
      * `ANTHROPIC_ENVIRONMENT_KEY`. With no arguments inside that command it just
      * works. Throws a clear error naming the first of the four required values
-     * still missing after resolution.
+     * still missing after resolution. Throws `SessionMemoryError` when the
+     * session has memory stores attached but they cannot be mounted — the work
+     * item carried no sessions token (unless `memorySyncIntervalMs` turned
+     * memory off), or a store failed to download.
+     *
+     * `workSecret` is the work item's per-item `secret` payload from the poll
+     * response, falling back to `ANTHROPIC_WORK_SECRET`; unlike the others it is
+     * optional — when present, the sessions token extracted from it is preferred
+     * as the Bearer credential for this item's heartbeat / force-stop / session
+     * calls; when absent (or undecodable) those calls use the environment key.
      */
     handleItem(opts?: HandleItemOptions): Promise<void>;
 }

package/lib/environments/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/lib/environments/worker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,wBAAqB;AAQ9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,qCAAkC;AAClE,OAAO,KAAK,EAAE,4BAA4B,EAAE,mCAAgC;AAU5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,0CAAuC;AAMvE;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAC9B,KAAK,CAAC,gBAAgB,CAAC,GACvB,CAAC,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAEzD,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,4BAA4B,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,iBAAiB;;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,iBAAiB,EAAE,OAAO,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,4BAA4B,GAAG,SAAS,CAAC;gBAGtD,IAAI,EAAE,wBAAwB;IAc1C;;;;OAIG;IACG,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB9C;;;;;;;;;;;;;;;;;OAiBG;IACG,UAAU,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAuH1D"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/lib/environments/worker.ts"],"names":[],"mappings":"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"}