@anthropic-ai/sdk 0.119.0 → 0.121.0

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

@@ -8,6 +8,17 @@
 export declare const DIR_CREATE_MODE = 493;
 /** Mode for files the file tools create. */
 export declare const FILE_CREATE_MODE = 420;
+/** True when `p` is `root` itself or lexically contained within it. */
+export declare function isWithin(root: string, p: string): boolean;
+/**
+ * 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 declare function containingRoot(roots: readonly string[], target: string): Promise<string | undefined>;
 /** The `code` of a Node system error, or `undefined` for anything else. */
 export declare function errnoCode(err: unknown): string | undefined;
 /**
@@ -25,17 +36,19 @@ export declare function errnoCode(err: unknown): string | undefined;
  */
 export declare 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
@@ -43,7 +56,7 @@ export declare function canonicalize(abs: string): Promise<string>;
  * sandbox is still recommended for the toolset as a whole.
  */
 export declare function confineToRoot(root: string, p: string, opts?: {
-    allowOutside?: boolean;
+    allowedRoots?: readonly string[];
 }): Promise<string>;
 /**
  * Atomically write `content` to `targetPath`: write a sibling temp file, fsync

package/tools/agent-toolset/fs-util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs-util.d.ts","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,uFAAuF;AACvF,eAAO,MAAM,eAAe,MAAQ,CAAC;AACrC,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AActC,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,OAAO,CAAC,MAAM,CAAC,CAejB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBxF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBjE"}
+{"version":3,"file":"fs-util.d.ts","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,uFAAuF;AACvF,eAAO,MAAM,eAAe,MAAQ,CAAC;AACrC,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AAEtC,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAK1G;AAKD,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B/D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC1C,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBxF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBjE"}

package/tools/agent-toolset/fs-util.js

@@ -7,6 +7,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FILE_CREATE_MODE = exports.DIR_CREATE_MODE = void 0;
+exports.isWithin = isWithin;
+exports.containingRoot = containingRoot;
 exports.errnoCode = errnoCode;
 exports.canonicalize = canonicalize;
 exports.confineToRoot = confineToRoot;
@@ -21,14 +23,25 @@ const ToolError_1 = require("../../lib/tools/ToolError.js");
 exports.DIR_CREATE_MODE = 0o755;
 /** Mode for files the file tools create. */
 exports.FILE_CREATE_MODE = 0o644;
-/** `realpath` `p`, or return `p` unchanged when it cannot be resolved. */
-async function realpathOrSelf(p) {
-    try {
-        return await fs.realpath(p);
-    }
-    catch {
-        return p;
+/** True when `p` is `root` itself or lexically contained within it. */
+function isWithin(root, p) {
+    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.
+ */
+async function containingRoot(roots, target) {
+    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. */
 const MAX_SYMLINK_HOPS = 40;
@@ -87,17 +100,19 @@ async function canonicalize(abs) {
     }
 }
 /**
- * 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
@@ -105,22 +120,22 @@ async function canonicalize(abs) {
  * sandbox is still recommended for the toolset as a whole.
  */
 async function confineToRoot(root, p, opts) {
-    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;
     try {
-        real = await canonicalize(abs);
+        real = await canonicalize(path.resolve(realRoot, p));
     }
     catch (err) {
         throw new ToolError_1.ToolError(fsErrorMessage(err, `path ${JSON.stringify(p)}`));
     }
-    if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
-        throw new ToolError_1.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_1.ToolError(`path ${JSON.stringify(p)} is outside ${permitted}`);
 }
 /**
  * Atomically write `content` to `targetPath`: write a sibling temp file, fsync

package/tools/agent-toolset/fs-util.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs-util.js","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fs-util.js","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"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"}

package/tools/agent-toolset/fs-util.mjs

@@ -12,14 +12,25 @@ import { ToolError } from "../../lib/tools/ToolError.mjs";
 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) {
-    try {
-        return await fs.realpath(p);
-    }
-    catch {
-        return p;
+/** True when `p` is `root` itself or lexically contained within it. */
+export function isWithin(root, p) {
+    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, target) {
+    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. */
 const MAX_SYMLINK_HOPS = 40;
@@ -78,17 +89,19 @@ export async function canonicalize(abs) {
     }
 }
 /**
- * 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
@@ -96,22 +109,22 @@ export async function canonicalize(abs) {
  * sandbox is still recommended for the toolset as a whole.
  */
 export async function confineToRoot(root, p, opts) {
-    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;
     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}`);
 }
 /**
  * Atomically write `content` to `targetPath`: write a sibling temp file, fsync

package/tools/agent-toolset/fs-util.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fs-util.mjs","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fs-util.mjs","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"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"}

package/tools/agent-toolset/memories.d.mts

@@ -0,0 +1,173 @@
+/**
+ * Session-level memory-store download and sync.
+ *
+ * A session may have several memory stores attached. This module resolves
+ * where each store's folder goes on disk, opens a {@link LocalFileStore}
+ * there, and reconciles each folder with its remote store — the merge rules
+ * live on {@link SessionMemoryStores}.
+ *
+ * Node-only (it sits on the filesystem-backed FileStore); like `skills.ts`,
+ * it is reachable through the shimmed `node.ts` entry point.
+ */
+import type { Anthropic } from "../../client.mjs";
+import { AnthropicError } from "../../core/error.mjs";
+import type { BetaManagedAgentsSession } from "../../resources/beta/sessions/sessions.mjs";
+export { DEFAULT_MEMORY_SYNC_INTERVAL_MS, MIN_MEMORY_SYNC_INTERVAL_MS } from "./sync-interval.mjs";
+/**
+ * Whether a locally deleted file may delete its memory on the server:
+ * `"enabled"` sends the delete, `"log_only"` runs the checks but only logs,
+ * `"disabled"` never deletes.
+ */
+export type MemoryDeleteMode = 'enabled' | 'log_only' | 'disabled';
+/**
+ * Time bound the worker puts on each teardown pass — the final
+ * {@link SessionMemoryStores.finish}, then {@link SessionMemoryStores.flushWrites} —
+ * so a slow server cannot stall teardown.
+ */
+export declare const MEMORY_FLUSH_TIMEOUT_MS = 30000;
+/**
+ * Marker file stamped into every store folder; a sync trusts the folder only
+ * when it matches. Never itself syncs.
+ */
+export declare const MARKER_PATH = ".anthropic-memory-store";
+/** How long a file must stay missing locally before its server delete goes out. */
+export declare const DELETE_CORROBORATION_MS = 30000;
+/**
+ * How many uploads one store's flush keeps in flight. At ~0.3s per upload,
+ * 32 clears the server's 2000-memories-per-store cap inside
+ * {@link MEMORY_FLUSH_TIMEOUT_MS}.
+ */
+export declare const UPLOAD_CONCURRENCY = 32;
+/**
+ * A session's memory stores could not be mounted.
+ *
+ * Thrown by {@link SessionMemoryStores.download} when a store cannot be
+ * materialised on disk, and by the environment worker when a work item for a
+ * session that has memory stores carried no sessions token to reach them with.
+ */
+export declare class SessionMemoryError extends AnthropicError {
+    constructor(message: string, cause?: unknown);
+}
+export interface SessionMemoryStoresOptions {
+    /** Base directory for the `{workdir}/memory/<name>` fallback store location. */
+    workdir: string;
+    /**
+     * How often (milliseconds) {@link SessionMemoryStores.syncIfDue} actually
+     * syncs. Defaults to {@link DEFAULT_MEMORY_SYNC_INTERVAL_MS} (15s); values
+     * below {@link MIN_MEMORY_SYNC_INTERVAL_MS} (5s) are rejected.
+     */
+    syncIntervalMs?: number;
+    /** See {@link MemoryDeleteMode}. Defaults to `"enabled"`. */
+    syncDeletions?: MemoryDeleteMode;
+}
+/**
+ * The memory stores attached to one session, materialised on disk.
+ *
+ * {@link SessionMemoryStores.download} opens a {@link LocalFileStore} at each
+ * attached store's directory (its `mount_path`, or a workdir fallback — see
+ * {@link SessionMemoryStores.download}), pulls its memories, and records each
+ * one's `content_sha256` as the sync baseline. Each sync
+ * ({@link SessionMemoryStores.syncIfDue} on the worker's cadence,
+ * {@link SessionMemoryStores.finish} once at the end) reconciles disk against
+ * server, per store and per path:
+ *
+ * - a memory changed only remotely is written to disk;
+ * - a file changed only locally is uploaded — an update with a
+ *   `content_sha256` precondition, or a create for a new file;
+ * - a file changed on both sides logs a warning and takes the server version;
+ * - a file the server refuses (too large, invalid content) is skipped —
+ *   warned once and retried only after the file changes; other files keep
+ *   syncing;
+ * - a file deleted locally is deleted on the server after a delay and a
+ *   re-check — never on the first sync that notices, and only up to a
+ *   per-sync cap. `syncDeletions` gates it;
+ * - a memory deleted on the server is deleted on disk — unless the local
+ *   file holds un-pushed edits: a writable store re-creates the memory
+ *   from the file, a read-only one keeps the file unsynced;
+ * - a store attached read-only pulls but never pushes.
+ *
+ * A download pulls the whole store, so it lists with content included. The
+ * recurring syncs instead run two phases: a content-free listing (paths and
+ * shas) drives the merge decisions, then only the memories actually being
+ * written to disk are fetched, a bounded number at a time. A sync that finds
+ * nothing changed moves no content at all.
+ *
+ * A file whose write to disk failed is never in the baseline, so its absence
+ * reads as a failed download — it is pulled again, never deleted. A write
+ * never re-creates a store folder that vanished mid-sync: it fails, and the
+ * next sync's scan finds whatever is at the path by then — nothing
+ * (re-downloaded) or someone else's files (left alone) — under the rules
+ * below.
+ *
+ * A store folder that loses its {@link MARKER_PATH} marker, is emptied,
+ * or vanishes is re-downloaded rather than treated as a mass local
+ * delete; a folder whose marker names another store is left as found —
+ * nothing pushed, nothing deleted.
+ *
+ * Two things about the store's directory make
+ * {@link SessionMemoryStores.download} refuse the session outright, with
+ * {@link SessionMemoryError}: a `mount_path` that is not a clean absolute
+ * path, and a directory already sitting at that path.
+ *
+ * {@link SessionMemoryStores.download} throws on the first store it cannot
+ * materialise. The syncs never throw: mid-session, one bad store or one bad
+ * file is logged and the rest continue. Instances are not safe for concurrent
+ * use. The worker builds one on its token-scoped sub-client (the memory
+ * endpoints reject the environment key): `syncIfDue` after each tool call,
+ * `finish` once at a clean end, a bounded {@link SessionMemoryStores.flushWrites}
+ * in every teardown, `dispose` last.
+ */
+export declare class SessionMemoryStores {
+    #private;
+    constructor(client: Anthropic, opts: SessionMemoryStoresOptions);
+    /**
+     * Every attached store's root directory.
+     *
+     * The worker lists these as the file tools' allowed roots so a store
+     * mounted outside the workdir stays reachable.
+     */
+    get roots(): string[];
+    /**
+     * Root directories of stores attached read-only.
+     *
+     * The file tools consult this to refuse writes into read-only stores.
+     */
+    get readOnlyRoots(): string[];
+    /**
+     * Download every attached store's memories to disk.
+     *
+     * `session` arrives already fetched — one snapshot shared with the skills
+     * download, so the two cannot disagree about the resources.
+     */
+    download(session: BetaManagedAgentsSession): Promise<void>;
+    /**
+     * The session's last sync — skips the delete wait, so calling it twice
+     * would undo the protection; it throws instead.
+     */
+    finish(): Promise<void>;
+    /** @internal — reconcile every store once; the tests' deterministic driver */
+    syncAll(final: boolean): Promise<void>;
+    /** Sync when `syncIntervalMs` has elapsed since the last one. Never throws. */
+    syncIfDue(): Promise<void>;
+    /**
+     * Upload new and changed files; send no deletes and pull nothing.
+     *
+     * The push-only rescue pass for a session ending on an error or
+     * cancel — best-effort, bounded by the caller: once `signal` aborts no
+     * further upload starts, each store cut off part-way logs how many
+     * changed files it had not finished uploading, and this resolves without
+     * waiting for requests already in flight. Each store uploads up to
+     * {@link UPLOAD_CONCURRENCY} files at a time. Skips read-only stores,
+     * refused files, files the server already holds, and folders that fail
+     * the marker check. Never throws.
+     */
+    flushWrites(signal?: AbortSignal): Promise<void>;
+    /**
+     * Remove every store directory that {@link SessionMemoryStores.download}
+     * created. Pre-existing directories are left alone — that is
+     * {@link FileStore.dispose}'s own rule. A folder that fails the marker
+     * check is kept too — sync left it as found, so must dispose.
+     */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=memories.d.mts.map

package/tools/agent-toolset/memories.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memories.d.mts","sourceRoot":"","sources":["../../src/tools/agent-toolset/memories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,yBAAqB;AAC9C,OAAO,EAAE,cAAc,EAAE,6BAAyB;AAKlD,OAAO,KAAK,EAAE,wBAAwB,EAAE,mDAA+C;AAQvF,OAAO,EAAE,+BAA+B,EAAE,2BAA2B,EAAE,4BAAwB;AAE/F;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,WAAW,4BAA4B,CAAC;AAQrD,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAgB9C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAoBrC;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,cAAc;gBACxC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAO7C;AAsCD,MAAM,WAAW,0BAA0B;IACzC,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,qBAAa,mBAAmB;;gBAUlB,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,0BAA0B;IAU/D;;;;;OAKG;IACH,IAAI,KAAK,IAAI,MAAM,EAAE,CAEpB;IAED;;;;OAIG;IACH,IAAI,aAAa,IAAI,MAAM,EAAE,CAE5B;IA0BD;;;;;OAKG;IACG,QAAQ,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IA6DhE;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ7B,8EAA8E;IACxE,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA8F5C,+EAA+E;IACzE,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAKhC;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkEtD;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAsb/B"}