@cursor/bdk 0.2.1

package/dist/internal/update-check.js

@@ -0,0 +1,427 @@
+/**
+ * Outdated-version warning + `agent-sdk update`.
+ *
+ * Every CLI run of a published install compares its own version against the
+ * npm registry's `latest` dist-tag and warns on stderr when behind. The
+ * registry lookup is cached under the config dir
+ * (`~/.config/agent-serve/update-check.json`) so most runs never touch the
+ * network; a stale cache refreshes inline under a short timeout, and any
+ * network failure is silent (the warning is best-effort, never a blocker).
+ *
+ * `agent-sdk update` re-runs the lookup fresh, figures out how this copy was
+ * installed (global npm/pnpm/yarn/bun, or a project dependency), and runs the
+ * matching install command.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { spawn } from "node:child_process";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, sep } from "node:path";
+import { z } from "zod";
+import { configDirPath } from "./cursor/credentials.js";
+import { describeError } from "./describe-error.js";
+import { CLI_COMMAND_NAME, isCompiledDistribution, PACKAGE_NAME, packageRootDir, packageVersion, } from "./distribution.js";
+import { stderrPalette } from "./terminal-style.js";
+const NPM_REGISTRY_URL = "https://registry.npmjs.org";
+/** Refresh the registry lookup at most this often. */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** Inline refresh budget; a slow registry must not stall the command. */
+const WARN_FETCH_TIMEOUT_MS = 1500;
+/** `agent-sdk update` runs interactively, so it can afford a real timeout. */
+const UPDATE_FETCH_TIMEOUT_MS = 10000;
+function parseVersion(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/.exec(version.trim());
+    if (match === null) {
+        return undefined;
+    }
+    return {
+        release: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease: match[4] === undefined ? [] : match[4].split("."),
+    };
+}
+/**
+ * Semver-style ordering: negative when `a < b`, 0 when equal, positive when
+ * `a > b`. Unparseable versions compare equal (never warn on garbage).
+ */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (pa === undefined || pb === undefined) {
+        return 0;
+    }
+    for (let i = 0; i < 3; i++) {
+        const diff = pa.release[i] - pb.release[i];
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    // A release outranks any prerelease of the same triple.
+    if (pa.prerelease.length === 0 || pb.prerelease.length === 0) {
+        return pb.prerelease.length - pa.prerelease.length;
+    }
+    const len = Math.max(pa.prerelease.length, pb.prerelease.length);
+    for (let i = 0; i < len; i++) {
+        const ia = pa.prerelease[i];
+        const ib = pb.prerelease[i];
+        // A longer prerelease list outranks its prefix (1.0.0-a.1 > 1.0.0-a).
+        if (ia === undefined) {
+            return -1;
+        }
+        if (ib === undefined) {
+            return 1;
+        }
+        const na = /^\d+$/.test(ia) ? Number(ia) : undefined;
+        const nb = /^\d+$/.test(ib) ? Number(ib) : undefined;
+        if (na !== undefined && nb !== undefined) {
+            if (na !== nb) {
+                return na - nb;
+            }
+        }
+        else if (na !== undefined) {
+            return -1; // numeric identifiers sort before alphanumeric ones
+        }
+        else if (nb !== undefined) {
+            return 1;
+        }
+        else if (ia !== ib) {
+            return ia < ib ? -1 : 1;
+        }
+    }
+    return 0;
+}
+// ============================================================================
+// Registry lookup
+// ============================================================================
+const distTagResponseSchema = z.object({ version: z.string() });
+/**
+ * Latest published version of the package, from the registry's `latest`
+ * dist-tag. Returns undefined on any failure (offline, 404 pre-publish, …).
+ */
+export function fetchLatestPublishedVersion(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const fetchImpl = (_a = options === null || options === void 0 ? void 0 : options.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        const packageName = (_b = options === null || options === void 0 ? void 0 : options.packageName) !== null && _b !== void 0 ? _b : PACKAGE_NAME;
+        // Scoped names keep the `@` but encode the `/` for the registry path.
+        const url = `${NPM_REGISTRY_URL}/${packageName.replace("/", "%2F")}/latest`;
+        try {
+            const response = yield fetchImpl(url, {
+                headers: { accept: "application/json" },
+                signal: AbortSignal.timeout((_c = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _c !== void 0 ? _c : WARN_FETCH_TIMEOUT_MS),
+            });
+            if (!response.ok) {
+                return undefined;
+            }
+            const body = distTagResponseSchema.safeParse(yield response.json());
+            if (!body.success || parseVersion(body.data.version) === undefined) {
+                return undefined;
+            }
+            return body.data.version;
+        }
+        catch (_d) {
+            return undefined;
+        }
+    });
+}
+// ============================================================================
+// Cache (one JSON file next to credentials.json)
+// ============================================================================
+const cacheSchema = z.object({
+    /** Epoch ms of the last registry lookup attempt (success or not). */
+    checkedAt: z.number(),
+    /** Last version the registry reported; absent when lookups keep failing. */
+    latestVersion: z.string().optional(),
+});
+export function updateCheckCachePath(configDir) {
+    return join(configDir !== null && configDir !== void 0 ? configDir : configDirPath(), "update-check.json");
+}
+export function readUpdateCheckCache(configDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let raw;
+        try {
+            raw = yield readFile(updateCheckCachePath(configDir), "utf8");
+        }
+        catch (_a) {
+            return undefined;
+        }
+        try {
+            const parsed = cacheSchema.safeParse(JSON.parse(raw));
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch (_b) {
+            return undefined;
+        }
+    });
+}
+export function writeUpdateCheckCache(cache, configDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const path = updateCheckCachePath(configDir);
+        try {
+            yield mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            yield writeFile(path, `${JSON.stringify(cache, null, 2)}\n`);
+        }
+        catch (_a) {
+            // Best-effort; a read-only config dir just means re-checking next run.
+        }
+    });
+}
+/**
+ * Print an outdated-version warning to stderr when a newer release exists.
+ *
+ * Never throws and never blocks longer than {@link WARN_FETCH_TIMEOUT_MS}.
+ * Suppressed on source-checkout runs (there is no installed copy to update),
+ * in CI, and via NO_UPDATE_NOTIFIER / AGENT_SERVE_NO_UPDATE_CHECK.
+ */
+export function warnIfOutdated(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        const env = (_a = options === null || options === void 0 ? void 0 : options.env) !== null && _a !== void 0 ? _a : process.env;
+        if (isTruthyEnv(env.AGENT_SERVE_NO_UPDATE_CHECK) ||
+            isTruthyEnv(env.NO_UPDATE_NOTIFIER) ||
+            isTruthyEnv(env.CI)) {
+            return;
+        }
+        if ((options === null || options === void 0 ? void 0 : options.force) !== true && !isCompiledDistribution()) {
+            return;
+        }
+        const now = (_b = options === null || options === void 0 ? void 0 : options.now) !== null && _b !== void 0 ? _b : Date.now();
+        const currentVersion = (_c = options === null || options === void 0 ? void 0 : options.currentVersion) !== null && _c !== void 0 ? _c : packageVersion();
+        const cached = yield readUpdateCheckCache(options === null || options === void 0 ? void 0 : options.configDir);
+        let latestVersion = cached === null || cached === void 0 ? void 0 : cached.latestVersion;
+        const fresh = cached !== undefined && now - cached.checkedAt < CHECK_INTERVAL_MS;
+        if (!fresh) {
+            const fetched = yield fetchLatestPublishedVersion({
+                fetchImpl: options === null || options === void 0 ? void 0 : options.fetchImpl,
+                timeoutMs: WARN_FETCH_TIMEOUT_MS,
+            });
+            latestVersion = fetched !== null && fetched !== void 0 ? fetched : latestVersion;
+            // checkedAt always advances so a flaky registry backs off to one
+            // attempt per interval instead of one per command.
+            yield writeUpdateCheckCache({ checkedAt: now, latestVersion }, options === null || options === void 0 ? void 0 : options.configDir);
+        }
+        if (latestVersion === undefined || compareVersions(currentVersion, latestVersion) >= 0) {
+            return;
+        }
+        const c = stderrPalette();
+        const err = (_d = options === null || options === void 0 ? void 0 : options.err) !== null && _d !== void 0 ? _d : ((text) => void process.stderr.write(text));
+        err(`${c.yellow("warning:")} ${CLI_COMMAND_NAME} ${currentVersion} is outdated (latest is ${latestVersion}). Run \`${CLI_COMMAND_NAME} update\` to upgrade.\n`);
+    });
+}
+function isTruthyEnv(value) {
+    return value !== undefined && value !== "" && value !== "0";
+}
+/**
+ * Figure out how the running copy was installed and which command upgrades
+ * it. Detection is path-shape based (global stores have recognizable
+ * layouts), then falls back to walking up to the project that declares the
+ * dependency. Returns undefined for layouts we cannot safely upgrade
+ * (npx cache, unrecognized stores).
+ */
+export function detectUpdateCommand(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const packageName = (_a = args.packageName) !== null && _a !== void 0 ? _a : PACKAGE_NAME;
+        const spec = `${packageName}@latest`;
+        const posixRoot = args.packageRoot.split(sep).join("/");
+        // npx / pnpm dlx caches are ephemeral; a fresh `npx agent-sdk` already
+        // resolves latest, and upgrading the cache entry in place helps nobody.
+        if (posixRoot.includes("/_npx/") || posixRoot.includes("/.pnpm-store/")) {
+            return undefined;
+        }
+        if (posixRoot.includes("/pnpm/global/")) {
+            return {
+                cmd: "pnpm",
+                args: ["add", "-g", spec],
+                reason: "installed with pnpm --global",
+            };
+        }
+        if (posixRoot.includes("/.bun/install/global/")) {
+            return {
+                cmd: "bun",
+                args: ["add", "-g", spec],
+                reason: "installed with bun --global",
+            };
+        }
+        if (posixRoot.includes("/yarn/global/") || posixRoot.includes("/.config/yarn/global/")) {
+            return {
+                cmd: "yarn",
+                args: ["global", "add", spec],
+                reason: "installed with yarn global",
+            };
+        }
+        // A project that depends on the package: upgrade the dependency there,
+        // with whichever package manager the lockfile says the project uses.
+        const projectDir = yield findDependingProjectDir(args.packageRoot, packageName);
+        if (projectDir !== undefined) {
+            const pm = yield detectProjectPackageManager(projectDir);
+            const command = pm === "pnpm"
+                ? { cmd: "pnpm", args: ["add", spec] }
+                : pm === "yarn"
+                    ? { cmd: "yarn", args: ["add", spec] }
+                    : pm === "bun"
+                        ? { cmd: "bun", args: ["add", spec] }
+                        : { cmd: "npm", args: ["install", spec] };
+            return Object.assign(Object.assign({}, command), { cwd: projectDir, reason: `project dependency in ${projectDir}` });
+        }
+        // Global npm layout: <prefix>/lib/node_modules/<name> (or <prefix>\
+        // node_modules\<name> on Windows), with no depending project above it.
+        if (posixRoot.includes("/node_modules/")) {
+            return {
+                cmd: "npm",
+                args: ["install", "-g", spec],
+                reason: "installed with npm --global",
+            };
+        }
+        return undefined;
+    });
+}
+/**
+ * Nearest ancestor with a package.json that declares `packageName` as a
+ * dependency. Skips directories inside node_modules (pnpm's virtual store
+ * nests package.json files that are not the user's project).
+ */
+function findDependingProjectDir(packageRoot, packageName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let dir = dirname(packageRoot);
+        for (let depth = 0; depth < 30; depth++) {
+            const parent = dirname(dir);
+            if (parent === dir) {
+                return undefined;
+            }
+            const inNodeModules = dir.split(sep).some(part => part === "node_modules" || part === ".pnpm");
+            if (!inNodeModules && (yield declaresDependency(dir, packageName))) {
+                return dir;
+            }
+            dir = parent;
+        }
+        return undefined;
+    });
+}
+function declaresDependency(dir, packageName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        let raw;
+        try {
+            raw = yield readFile(join(dir, "package.json"), "utf8");
+        }
+        catch (_c) {
+            return false;
+        }
+        const manifestSchema = z.object({
+            dependencies: z.record(z.string()).optional(),
+            devDependencies: z.record(z.string()).optional(),
+        });
+        try {
+            const parsed = manifestSchema.safeParse(JSON.parse(raw));
+            if (!parsed.success) {
+                return false;
+            }
+            return (((_a = parsed.data.dependencies) === null || _a === void 0 ? void 0 : _a[packageName]) !== undefined ||
+                ((_b = parsed.data.devDependencies) === null || _b === void 0 ? void 0 : _b[packageName]) !== undefined);
+        }
+        catch (_d) {
+            return false;
+        }
+    });
+}
+function detectProjectPackageManager(projectDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const exists = (file) => __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield stat(join(projectDir, file));
+                return true;
+            }
+            catch (_a) {
+                return false;
+            }
+        });
+        if (yield exists("pnpm-lock.yaml")) {
+            return "pnpm";
+        }
+        if (yield exists("yarn.lock")) {
+            return "yarn";
+        }
+        if ((yield exists("bun.lock")) || (yield exists("bun.lockb"))) {
+            return "bun";
+        }
+        return "npm";
+    });
+}
+/** `agent-sdk update` — upgrade this install to the latest published version. */
+export function cmdUpdate(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f;
+        const c = stderrPalette();
+        const out = (_a = options === null || options === void 0 ? void 0 : options.out) !== null && _a !== void 0 ? _a : ((text) => void process.stdout.write(text));
+        const err = (_b = options === null || options === void 0 ? void 0 : options.err) !== null && _b !== void 0 ? _b : ((text) => void process.stderr.write(text));
+        const compiled = (_c = options === null || options === void 0 ? void 0 : options.compiled) !== null && _c !== void 0 ? _c : isCompiledDistribution();
+        if (!compiled) {
+            err(`${CLI_COMMAND_NAME} is running from a source checkout, not an installed package; update it with git instead.\n`);
+            return 1;
+        }
+        const currentVersion = (_d = options === null || options === void 0 ? void 0 : options.currentVersion) !== null && _d !== void 0 ? _d : packageVersion();
+        const latestVersion = yield fetchLatestPublishedVersion({
+            fetchImpl: options === null || options === void 0 ? void 0 : options.fetchImpl,
+            timeoutMs: UPDATE_FETCH_TIMEOUT_MS,
+        });
+        if (latestVersion === undefined) {
+            err(`Could not reach the npm registry to look up the latest ${PACKAGE_NAME} version. Check your network and retry.\n`);
+            return 1;
+        }
+        if (compareVersions(currentVersion, latestVersion) >= 0) {
+            out(`${CLI_COMMAND_NAME} ${currentVersion} is already the latest version.\n`);
+            yield writeUpdateCheckCache({ checkedAt: Date.now(), latestVersion }, options === null || options === void 0 ? void 0 : options.configDir);
+            return 0;
+        }
+        const command = yield detectUpdateCommand({
+            packageRoot: (_e = options === null || options === void 0 ? void 0 : options.packageRoot) !== null && _e !== void 0 ? _e : packageRootDir(),
+        });
+        if (command === undefined) {
+            err(`${CLI_COMMAND_NAME} ${currentVersion} is outdated (latest is ${latestVersion}), but this install's layout was not recognized.\nUpgrade it yourself, e.g. \`npm install -g ${PACKAGE_NAME}@latest\` for a global install, or bump the ${PACKAGE_NAME} dependency in your project.\n`);
+            return 1;
+        }
+        const rendered = [command.cmd, ...command.args].join(" ");
+        err(c.dim(`Updating ${CLI_COMMAND_NAME} ${currentVersion} → ${latestVersion} (${command.reason}):\n  ${rendered}\n`));
+        const run = (_f = options === null || options === void 0 ? void 0 : options.runCommand) !== null && _f !== void 0 ? _f : runUpdateCommand;
+        let code;
+        try {
+            code = yield run(command);
+        }
+        catch (error) {
+            err(`\`${rendered}\` failed: ${describeError(error)}\n`);
+            return 1;
+        }
+        if (code !== 0) {
+            err(`\`${rendered}\` exited with code ${code}.\n`);
+            return code;
+        }
+        yield writeUpdateCheckCache({ checkedAt: Date.now(), latestVersion }, options === null || options === void 0 ? void 0 : options.configDir);
+        out(`Updated ${CLI_COMMAND_NAME} to ${latestVersion}. New commands run the new version.\n`);
+        return 0;
+    });
+}
+function runUpdateCommand(command) {
+    return new Promise((resolve, reject) => {
+        // Windows-only shell: npm/pnpm/yarn/bun are .cmd shims there, and Node
+        // refuses to spawn .cmd files without a shell (EINVAL, CVE-2024-27980
+        // hardening). Injection-safe: cmd and args are module-level constants
+        // from detectUpdateCommand (never user or registry input).
+        // nosemgrep: javascript.lang.security.audit.spawn-shell-true.spawn-shell-true
+        const child = spawn(command.cmd, command.args, {
+            stdio: "inherit",
+            cwd: command.cwd,
+            shell: process.platform === "win32",
+        });
+        child.on("error", reject);
+        child.on("close", code => {
+            resolve(code !== null && code !== void 0 ? code : 1);
+        });
+    });
+}

package/dist/internal/v2-hosting.d.ts

@@ -0,0 +1,31 @@
+import type { AgentArchitecture } from "../types.js";
+import { type CursorManagedV2StoreIds } from "./cursor/hosted-store-secrets.js";
+/**
+ * Exported (as `1`) by the control plane's start script for a version
+ * container of a persistent deployment. Its presence, not the agent's
+ * `persistent` flag, is what tells the runtime it owns a durable state
+ * directory.
+ */
+export declare const AGENT_SERVE_PERSISTENT_ENV_VAR = "AGENT_SERVE_PERSISTENT";
+export type AgentV2Hosting = {
+    kind: "not-v2";
+} | {
+    kind: "self-hosted";
+} | {
+    kind: "cursor-managed";
+    resolveStoreIds: () => CursorManagedV2StoreIds;
+} | {
+    kind: "cursor-managed-persistent";
+};
+/**
+ * Close the architecture/hosting inputs into a compiler-owned union.
+ *
+ * Managed freeze processes exist before task bind, so store resolution stays
+ * lazy. Consumers can branch once on `kind`; managed storage operations then
+ * receive a resolver whose successful result always contains both ids.
+ */
+export declare function resolveAgentV2Hosting(input: {
+    architecture: AgentArchitecture | undefined;
+    env?: NodeJS.ProcessEnv;
+}): AgentV2Hosting;
+//# sourceMappingURL=v2-hosting.d.ts.map

package/dist/internal/v2-hosting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2-hosting.d.ts","sourceRoot":"","sources":["../../src/internal/v2-hosting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,kCAAkC,CAAC;AAG1C;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,2BAA2B,CAAC;AAEvE,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IACE,IAAI,EAAE,gBAAgB,CAAC;IACvB,eAAe,EAAE,MAAM,uBAAuB,CAAC;CAChD,GACD;IACE,IAAI,EAAE,2BAA2B,CAAC;CACnC,CAAC;AAEN;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,YAAY,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG,cAAc,CAejB"}

package/dist/internal/v2-hosting.js

@@ -0,0 +1,33 @@
+import { requireCursorManagedV2StoreIdsSync, } from "./cursor/hosted-store-secrets.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+/**
+ * Exported (as `1`) by the control plane's start script for a version
+ * container of a persistent deployment. Its presence, not the agent's
+ * `persistent` flag, is what tells the runtime it owns a durable state
+ * directory.
+ */
+export const AGENT_SERVE_PERSISTENT_ENV_VAR = "AGENT_SERVE_PERSISTENT";
+/**
+ * Close the architecture/hosting inputs into a compiler-owned union.
+ *
+ * Managed freeze processes exist before task bind, so store resolution stays
+ * lazy. Consumers can branch once on `kind`; managed storage operations then
+ * receive a resolver whose successful result always contains both ids.
+ */
+export function resolveAgentV2Hosting(input) {
+    var _a;
+    if (input.architecture !== "v2") {
+        return { kind: "not-v2" };
+    }
+    const env = (_a = input.env) !== null && _a !== void 0 ? _a : process.env;
+    if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+        return { kind: "self-hosted" };
+    }
+    if (env[AGENT_SERVE_PERSISTENT_ENV_VAR] === "1") {
+        return { kind: "cursor-managed-persistent" };
+    }
+    return {
+        kind: "cursor-managed",
+        resolveStoreIds: () => requireCursorManagedV2StoreIdsSync(env),
+    };
+}

package/dist/internal/workspace-sync.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Sync workspace trees onto an Agent Store so cloud-runtime turns read
+ * them from the store mount. Authored `agent/sandbox/workspace/**` seeds
+ * land at store-root `workspace/<path>` (see `buildCloudWorkspaceSection`).
+ * Per-turn `workspaceFiles` land at `sessions/<sessionId>/workspace/<path>`
+ * (see `buildCloudSessionWorkspaceSection`). Personal-key local+cloud
+ * nests both under `agent-serve/<agent>/`.
+ */
+import { type FileSink } from "../files.js";
+import type { SeedFile } from "../types.js";
+export type WorkspaceFileBody = string | {
+    encoding: "base64";
+    data: string;
+    mimeType?: string;
+};
+/** Path or encoding that can never land. Distinct from a store outage. */
+export declare class WorkspaceFileRefusal extends Error {
+    readonly name = "WorkspaceFileRefusal";
+}
+/**
+ * Mirror the seed tree onto the store at its authored relative paths and
+ * delete keys no seed claims so redeploys drop removed files. Every seed
+ * loads and validates before the store is touched.
+ */
+export declare function syncWorkspaceToStore(args: {
+    sink: FileSink;
+    seedFiles: readonly SeedFile[];
+    /** Store-root directory that holds the seed tree. Defaults to `workspace/`. */
+    workspacePrefix?: string;
+}): Promise<void>;
+/**
+ * Replace the session workspace prefix with this turn's `workspaceFiles`.
+ * Keys the map does not claim are deleted so a later send cannot leave a
+ * stale `pr.json`. Every path validates before the store is touched.
+ * Returns the relative paths that landed, in send order.
+ */
+export declare function syncSessionWorkspaceFiles(args: {
+    sink: FileSink;
+    files: Record<string, WorkspaceFileBody>;
+    workspacePrefix: string;
+}): Promise<string[]>;
+/** Delete every key under the session workspace prefix. */
+export declare function wipeSessionWorkspace(args: {
+    sink: FileSink;
+    workspacePrefix: string;
+}): Promise<void>;
+//# sourceMappingURL=workspace-sync.d.ts.map

package/dist/internal/workspace-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-sync.d.ts","sourceRoot":"","sources":["../../src/internal/workspace-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjG,0EAA0E;AAC1E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAA0B;CACjD;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzC,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBpB;AAED,2DAA2D;AAC3D,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,IAAI,EAAE,QAAQ,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhB"}

package/dist/internal/workspace-sync.js

@@ -0,0 +1,104 @@
+/**
+ * Sync workspace trees onto an Agent Store so cloud-runtime turns read
+ * them from the store mount. Authored `agent/sandbox/workspace/**` seeds
+ * land at store-root `workspace/<path>` (see `buildCloudWorkspaceSection`).
+ * Per-turn `workspaceFiles` land at `sessions/<sessionId>/workspace/<path>`
+ * (see `buildCloudSessionWorkspaceSection`). Personal-key local+cloud
+ * nests both under `agent-serve/<agent>/`.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { readFile } from "node:fs/promises";
+import { agentStoreKeys } from "../files.js";
+import { MEMORY_DIR_NAME } from "../memory.js";
+import { mirrorToStore, storeRelPath } from "./store-mirror.js";
+/** Path or encoding that can never land. Distinct from a store outage. */
+export class WorkspaceFileRefusal extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "WorkspaceFileRefusal";
+    }
+}
+/**
+ * Mirror the seed tree onto the store at its authored relative paths and
+ * delete keys no seed claims so redeploys drop removed files. Every seed
+ * loads and validates before the store is touched.
+ */
+export function syncWorkspaceToStore(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const workspacePrefix = (_a = args.workspacePrefix) !== null && _a !== void 0 ? _a : agentStoreKeys.workspacePrefix();
+        const desired = new Map();
+        for (const seed of args.seedFiles) {
+            desired.set(agentStoreKeys.workspaceFile(workspaceRelPath(seed.relativePath), workspacePrefix), yield readFile(seed.sourcePath));
+        }
+        yield mirrorToStore({ sink: args.sink, prefix: workspacePrefix, desired });
+    });
+}
+/**
+ * Replace the session workspace prefix with this turn's `workspaceFiles`.
+ * Keys the map does not claim are deleted so a later send cannot leave a
+ * stale `pr.json`. Every path validates before the store is touched.
+ * Returns the relative paths that landed, in send order.
+ */
+export function syncSessionWorkspaceFiles(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const desired = new Map();
+        const relPaths = [];
+        for (const [relativePath, contents] of Object.entries(args.files)) {
+            const rel = workspaceRelPath(relativePath);
+            desired.set(agentStoreKeys.workspaceFile(rel, args.workspacePrefix), workspaceFileBytes(relativePath, contents));
+            relPaths.push(rel);
+        }
+        yield mirrorToStore({
+            sink: args.sink,
+            prefix: args.workspacePrefix,
+            desired,
+        });
+        return relPaths;
+    });
+}
+/** Delete every key under the session workspace prefix. */
+export function wipeSessionWorkspace(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield mirrorToStore({
+            sink: args.sink,
+            prefix: args.workspacePrefix,
+            desired: new Map(),
+        });
+    });
+}
+/**
+ * Same reservation as local materialization's `resolveWorkspaceWritePath`:
+ * `memory/` is the shared cross-session journal, so a seed or send under it
+ * fails the sync exactly as it fails a local first turn.
+ */
+function workspaceRelPath(relPath) {
+    let rel;
+    try {
+        rel = storeRelPath(relPath, "workspace file");
+    }
+    catch (error) {
+        throw new WorkspaceFileRefusal(error instanceof Error ? error.message : String(error));
+    }
+    if (rel.split("/", 1)[0] === MEMORY_DIR_NAME) {
+        throw new WorkspaceFileRefusal(`"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to sync ${relPath}`);
+    }
+    return rel;
+}
+function workspaceFileBytes(relativePath, contents) {
+    if (typeof contents === "string") {
+        return new TextEncoder().encode(contents);
+    }
+    if (contents.encoding === "base64") {
+        return new Uint8Array(Buffer.from(contents.data, "base64"));
+    }
+    throw new WorkspaceFileRefusal(`Unsupported workspace file encoding for ${relativePath}`);
+}