@puku-ai/sdk 4.0.0 → 4.0.2

package/dist/vendor/resources/skills/versions.d.ts

@@ -0,0 +1,103 @@
+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';
+export declare class Versions extends APIResource {
+    /**
+     * Create Skill Version
+     */
+    create(skillID: string, body: VersionCreateParams, options?: RequestOptions): APIPromise<SkillVersion>;
+    /**
+     * Get Skill Version
+     */
+    retrieve(version: string, params: VersionRetrieveParams, options?: RequestOptions): APIPromise<SkillVersion>;
+    /**
+     * List Skill Versions
+     */
+    list(skillID: string, query?: VersionListParams | null | undefined, options?: RequestOptions): PagePromise<SkillVersionsPageCursor, SkillVersion>;
+    /**
+     * Delete Skill Version
+     */
+    delete(version: string, params: VersionDeleteParams, options?: RequestOptions): APIPromise<DeletedSkillVersion>;
+}
+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/dist/vendor/resources/skills/versions.js

@@ -0,0 +1,37 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import { APIResource } from '../../core/resource.js';
+import { PageCursor } from '../../core/pagination.js';
+import { multipartFormRequestOptions } from '../../internal/uploads.js';
+import { path } from '../../internal/utils/path.js';
+export class Versions extends APIResource {
+    /**
+     * Create Skill Version
+     */
+    create(skillID, body, options) {
+        return this._client.post(path `/v1/skills/${skillID}/versions`, multipartFormRequestOptions({ body, ...options }, this._client, false));
+    }
+    /**
+     * Get Skill Version
+     */
+    retrieve(version, params, options) {
+        const { skill_id } = params;
+        return this._client.get(path `/v1/skills/${skill_id}/versions/${version}`, options);
+    }
+    /**
+     * List Skill Versions
+     */
+    list(skillID, query = {}, options) {
+        return this._client.getAPIList(path `/v1/skills/${skillID}/versions`, (PageCursor), {
+            query,
+            ...options,
+        });
+    }
+    /**
+     * Delete Skill Version
+     */
+    delete(version, params, options) {
+        const { skill_id } = params;
+        return this._client.delete(path `/v1/skills/${skill_id}/versions/${version}`, options);
+    }
+}
+//# sourceMappingURL=versions.js.map

package/dist/vendor/resources/skills/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../../../src/vendor/resources/skills/versions.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,UAAU,EAAsC,MAAM,uBAAuB,CAAC;AAGvF,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAC;AAEjD,MAAM,OAAO,QAAS,SAAQ,WAAW;IACvC;;OAEG;IACH,MAAM,CAAC,OAAe,EAAE,IAAyB,EAAE,OAAwB;QACzE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CACtB,IAAI,CAAA,cAAc,OAAO,WAAW,EACpC,2BAA2B,CAAC,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CACvE,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,QAAQ,CACN,OAAe,EACf,MAA6B,EAC7B,OAAwB;QAExB,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,cAAc,QAAQ,aAAa,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;IACrF,CAAC;IAED;;OAEG;IACH,IAAI,CACF,OAAe,EACf,QAA8C,EAAE,EAChD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAA,cAAc,OAAO,WAAW,EAAE,CAAA,UAAwB,CAAA,EAAE;YAC7F,KAAK;YACL,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CACJ,OAAe,EACf,MAA2B,EAC3B,OAAwB;QAExB,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,cAAc,QAAQ,aAAa,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;IACxF,CAAC;CACF"}

package/dist/vendor/resources/skills.d.ts

@@ -0,0 +1 @@
+export * from './skills/index';

package/dist/vendor/resources/skills.js

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

package/dist/vendor/resources/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../../src/vendor/resources/skills.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,cAAc,gBAAgB,CAAC"}

package/dist/vendor/resources/top-level.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/vendor/resources/top-level.js

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+export {};
+//# sourceMappingURL=top-level.js.map

package/dist/vendor/resources/top-level.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"top-level.js","sourceRoot":"","sources":["../../../src/vendor/resources/top-level.ts"],"names":[],"mappings":"AAAA,sFAAsF"}

package/dist/vendor/resources.d.ts

@@ -0,0 +1 @@
+export * from './resources/index';

package/dist/vendor/resources.js

@@ -0,0 +1,2 @@
+export * from './resources/index.js';
+//# sourceMappingURL=resources.js.map

package/dist/vendor/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../../src/vendor/resources.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/vendor/streaming.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/streaming instead */
+export * from './core/streaming';

package/dist/vendor/streaming.js

@@ -0,0 +1,3 @@
+/** @deprecated Import from ./core/streaming instead */
+export * from './core/streaming.js';
+//# sourceMappingURL=streaming.js.map

package/dist/vendor/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../src/vendor/streaming.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,cAAc,kBAAkB,CAAC"}

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

@@ -0,0 +1,74 @@
+/**
+ * Shared, Node-only filesystem helpers for the agent toolset's file tools:
+ * path confinement (symlink-aware), an atomic write, and language-independent
+ * error messages. Kept out of `node.ts` so the tool implementations stay focused
+ * and these helpers can be reused by every file tool.
+ */
+/** Mode for directories the file tools create — not world-writable under a 0 umask. */
+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;
+/**
+ * Fully resolve `abs`: `realpath` the longest existing ancestor and re-append
+ * the rest, but never re-append a component that is itself a symlink — read the
+ * link and continue from its target instead. This handles paths being created
+ * (write/edit) without letting a symlink leaf (e.g. a dangling one pointing
+ * outside a confinement root) slip through unresolved.
+ *
+ * Returns a symlink-free path or throws an errno-carrying error (`ELOOP` for a
+ * cycle or more than {@link MAX_SYMLINK_HOPS} links, the `lstat`/`realpath`
+ * error for an unreadable component); it never returns `abs` unresolved. Only
+ * symlink hops count against the cap, so any depth of not-yet-existing
+ * directories still resolves.
+ */
+export declare function canonicalize(abs: string): Promise<string>;
+/**
+ * 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 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
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; this is why a
+ * sandbox is still recommended for the toolset as a whole.
+ */
+export declare function confineToRoot(root: string, p: string, opts?: {
+    allowedRoots?: readonly string[];
+}): Promise<string>;
+/**
+ * Atomically write `content` to `targetPath`: write a sibling temp file, fsync
+ * it, then rename over the target. The rename is atomic on most filesystems, so
+ * a crash mid-write never leaves the target half-written.
+ */
+export declare function atomicWriteFile(targetPath: string, content: string): Promise<void>;
+/**
+ * Map a thrown filesystem error to a consistent, language-independent message,
+ * so the model sees the same wording regardless of the runtime (Node's raw
+ * `ENOENT: no such file...` text would otherwise leak through). Codes we don't
+ * special-case render as the bare code, never Node's message, which embeds the
+ * host's absolute path.
+ */
+export declare function fsErrorMessage(err: unknown, file: string): string;

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

@@ -0,0 +1,184 @@
+/**
+ * Shared, Node-only filesystem helpers for the agent toolset's file tools:
+ * path confinement (symlink-aware), an atomic write, and language-independent
+ * error messages. Kept out of `node.ts` so the tool implementations stay focused
+ * and these helpers can be reused by every file tool.
+ */
+import { crypto, fs as nodefs, path } from '../../internal/node.js';
+import { ToolError } from '../../lib/tools/ToolError.js';
+const fs = nodefs.promises;
+/** Mode for directories the file tools create — not world-writable under a 0 umask. */
+export const DIR_CREATE_MODE = 0o755;
+/** Mode for files the file tools create. */
+export const FILE_CREATE_MODE = 0o644;
+/** 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;
+/** The `code` of a Node system error, or `undefined` for anything else. */
+export function errnoCode(err) {
+    const code = err?.code;
+    return typeof code === 'string' ? code : undefined;
+}
+/**
+ * Fully resolve `abs`: `realpath` the longest existing ancestor and re-append
+ * the rest, but never re-append a component that is itself a symlink — read the
+ * link and continue from its target instead. This handles paths being created
+ * (write/edit) without letting a symlink leaf (e.g. a dangling one pointing
+ * outside a confinement root) slip through unresolved.
+ *
+ * Returns a symlink-free path or throws an errno-carrying error (`ELOOP` for a
+ * cycle or more than {@link MAX_SYMLINK_HOPS} links, the `lstat`/`realpath`
+ * error for an unreadable component); it never returns `abs` unresolved. Only
+ * symlink hops count against the cap, so any depth of not-yet-existing
+ * directories still resolves.
+ */
+export async function canonicalize(abs) {
+    const tail = [];
+    let prefix = abs;
+    let hops = 0;
+    for (;;) {
+        let real;
+        try {
+            real = await fs.realpath(prefix);
+        }
+        catch (realpathErr) {
+            let isLink;
+            try {
+                isLink = (await fs.lstat(prefix)).isSymbolicLink();
+            }
+            catch (lstatErr) {
+                const code = errnoCode(lstatErr);
+                if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                    throw lstatErr;
+                const parent = path.dirname(prefix);
+                if (parent === prefix)
+                    throw lstatErr;
+                tail.push(path.basename(prefix));
+                prefix = parent;
+                continue;
+            }
+            if (!isLink)
+                throw realpathErr;
+            if (++hops > MAX_SYMLINK_HOPS) {
+                throw Object.assign(new Error('too many levels of symbolic links'), { code: 'ELOOP' });
+            }
+            prefix = path.resolve(path.dirname(prefix), await fs.readlink(prefix));
+            continue;
+        }
+        return tail.length ? path.join(real, ...tail.reverse()) : real;
+    }
+}
+/**
+ * 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 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
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; this is why a
+ * sandbox is still recommended for the toolset as a whole.
+ */
+export async function confineToRoot(root, p, opts) {
+    const allowedRoots = opts?.allowedRoots ?? [];
+    const realRoot = await canonicalize(path.resolve(root));
+    let real;
+    try {
+        real = await canonicalize(path.resolve(realRoot, p));
+    }
+    catch (err) {
+        throw new ToolError(fsErrorMessage(err, `path ${JSON.stringify(p)}`));
+    }
+    if (isWithin(realRoot, real) || (await containingRoot(allowedRoots, real)) !== undefined) {
+        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
+ * it, then rename over the target. The rename is atomic on most filesystems, so
+ * a crash mid-write never leaves the target half-written.
+ */
+export async function atomicWriteFile(targetPath, content) {
+    const dir = path.dirname(targetPath);
+    const tempPath = path.join(dir, `.tmp-${process.pid}-${crypto.randomUUID()}`);
+    let handle;
+    try {
+        handle = await fs.open(tempPath, 'wx', FILE_CREATE_MODE);
+        await handle.writeFile(content, 'utf-8');
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fs.rename(tempPath, targetPath);
+    }
+    catch (err) {
+        if (handle)
+            await handle.close().catch(() => { });
+        await fs.unlink(tempPath).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Map a thrown filesystem error to a consistent, language-independent message,
+ * so the model sees the same wording regardless of the runtime (Node's raw
+ * `ENOENT: no such file...` text would otherwise leak through). Codes we don't
+ * special-case render as the bare code, never Node's message, which embeds the
+ * host's absolute path.
+ */
+export function fsErrorMessage(err, file) {
+    const code = errnoCode(err);
+    switch (code) {
+        case 'ENOENT':
+            return `${file}: no such file or directory`;
+        case 'EACCES':
+        case 'EPERM':
+            return `${file}: permission denied`;
+        case 'ENOTDIR':
+            return `${file}: not a directory`;
+        case 'EISDIR':
+            return `${file}: is a directory`;
+        case 'ELOOP':
+            return `${file}: too many levels of symbolic links`;
+        case 'ENAMETOOLONG':
+            return `${file}: file name too long`;
+        case 'ENOSPC':
+            return `${file}: no space left on device`;
+        case 'EMFILE':
+        case 'ENFILE':
+            return `${file}: too many open files`;
+        default:
+            return `${file}: ${code !== undefined ? `i/o error (${code})` : 'i/o error'}`;
+    }
+}
+//# sourceMappingURL=fs-util.js.map

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

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

package/dist/vendor/tools/agent-toolset/memories.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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 { PukuAI } from '../../client';
+import { PukuError } from '../../core/error';
+import type { BetaManagedAgentsSession } from '../../resources/beta/sessions/sessions';
+export { DEFAULT_MEMORY_SYNC_INTERVAL_MS, MIN_MEMORY_SYNC_INTERVAL_MS } from './sync-interval';
+/**
+ * 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 = ".puku-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 PukuError {
+    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: PukuAI, 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>;
+}