@cursor/july 0.1.104 → 0.1.105

package/dist/internal/tenant-slack/relay.js

@@ -76,13 +76,16 @@ function describeError(error) {
  */
 export function postRelaySlackMessage(args) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         const channel = args.channel.trim();
+        const log = (_a = args.log) !== null && _a !== void 0 ? _a : ((line) => console.info(line));
         if (channel === "") {
+            log(`[agent-sdk-slack-relay-client] refusing post automationUuid=${args.automationUuid}: empty channel`);
             return { ok: false, channel, status: 0, error: "empty channel" };
         }
-        const target = ((_a = args.resolve) !== null && _a !== void 0 ? _a : resolveRelaySlackTarget)();
+        const target = ((_b = args.resolve) !== null && _b !== void 0 ? _b : resolveRelaySlackTarget)();
         if (target === undefined) {
+            log(`[agent-sdk-slack-relay-client] refusing post automationUuid=${args.automationUuid} channel=${channel}: no Cursor credential resolved (CURSOR_API_KEY / pod credential absent)`);
             return {
                 ok: false,
                 channel,
@@ -90,11 +93,14 @@ export function postRelaySlackMessage(args) {
                 error: "no Cursor credential for the Slack relay",
             };
         }
-        const fetchImpl = (_b = args.fetchImpl) !== null && _b !== void 0 ? _b : fetch;
+        const fetchImpl = (_c = args.fetchImpl) !== null && _c !== void 0 ? _c : fetch;
         const url = relaySlackPostUrl({
             baseUrl: target.relayBaseUrl,
             automationUuid: args.automationUuid,
         });
+        const messageChars = args.message.length;
+        log(`[agent-sdk-slack-relay-client] POST ${url} channel=${channel} messageChars=${String(messageChars)} truncated=${String(messageChars > AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS)} threaded=${String(args.threadTs !== undefined)} timeoutMs=${String((_d = args.timeoutMs) !== null && _d !== void 0 ? _d : DEFAULT_TIMEOUT_MS)}`);
+        const startedAt = Date.now();
         let response;
         try {
             response = yield fetchImpl(url, {
@@ -105,32 +111,36 @@ export function postRelaySlackMessage(args) {
                     accept: "application/json",
                 },
                 body: JSON.stringify(Object.assign({ channel, message: truncateMessage(args.message) }, (args.threadTs === undefined ? {} : { threadTs: args.threadTs }))),
-                signal: AbortSignal.timeout((_c = args.timeoutMs) !== null && _c !== void 0 ? _c : DEFAULT_TIMEOUT_MS),
+                signal: AbortSignal.timeout((_e = args.timeoutMs) !== null && _e !== void 0 ? _e : DEFAULT_TIMEOUT_MS),
             });
         }
         catch (error) {
+            log(`[agent-sdk-slack-relay-client] request failed before a response channel=${channel} automationUuid=${args.automationUuid} elapsedMs=${String(Date.now() - startedAt)}: ${describeError(error)}`);
             return { ok: false, channel, status: 0, error: describeError(error) };
         }
         let body;
         try {
             body = yield response.json();
         }
-        catch (_d) {
+        catch (_f) {
             body = undefined;
         }
         const record = typeof body === "object" && body !== null && !Array.isArray(body)
             ? body
             : {};
         if (!response.ok || record.ok !== true) {
+            const error = typeof record.error === "string" && record.error !== ""
+                ? record.error
+                : `relay responded ${response.status}`;
+            log(`[agent-sdk-slack-relay-client] relay denied channel=${channel} automationUuid=${args.automationUuid} status=${String(response.status)} bodyOk=${String(record.ok)} elapsedMs=${String(Date.now() - startedAt)}: ${error}`);
             return {
                 ok: false,
                 channel,
                 status: response.status,
-                error: typeof record.error === "string" && record.error !== ""
-                    ? record.error
-                    : `relay responded ${response.status}`,
+                error,
             };
         }
+        log(`[agent-sdk-slack-relay-client] relay posted channel=${typeof record.channel === "string" ? record.channel : channel} automationUuid=${args.automationUuid} status=${String(response.status)} ts=${typeof record.ts === "string" ? record.ts : "<none>"} elapsedMs=${String(Date.now() - startedAt)}`);
         return Object.assign(Object.assign({ ok: true, channel: typeof record.channel === "string" ? record.channel : channel }, (typeof record.ts === "string" ? { ts: record.ts } : {})), (typeof record.permalink === "string"
             ? { permalink: record.permalink }
             : {}));

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

@@ -1,13 +1,22 @@
 /**
- * Sync `agent/sandbox/workspace/**` seed files onto an Agent Store so
- * cloud-runtime turns read them from the store mount (the first cloud prompt
- * names the directory; see `buildCloudWorkspaceSection`). Hosted deployments
- * write store-root `workspace/<path>`. Local `serve`/`run` with
- * `runtime: "cloud"` writes `agent-serve/<agent>/workspace/<path>` on the
- * USER store.
+ * 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
@@ -19,4 +28,20 @@ export declare function syncWorkspaceToStore(args: {
     /** 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

@@ -1 +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;;;;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,CAchB"}
+{"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,GACzB,MAAM,GACN;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,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,CAchB;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

@@ -1,10 +1,10 @@
 /**
- * Sync `agent/sandbox/workspace/**` seed files onto an Agent Store so
- * cloud-runtime turns read them from the store mount (the first cloud prompt
- * names the directory; see `buildCloudWorkspaceSection`). Hosted deployments
- * write store-root `workspace/<path>`. Local `serve`/`run` with
- * `runtime: "cloud"` writes `agent-serve/<agent>/workspace/<path>` on the
- * USER store.
+ * 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); }); }
@@ -19,6 +19,13 @@ 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
@@ -30,20 +37,68 @@ export function syncWorkspaceToStore(args) {
         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(seedRelPath(seed.relativePath), workspacePrefix), yield readFile(seed.sourcePath));
+            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 under it fails
- * the sync exactly as it fails a local first turn.
+ * `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 seedRelPath(relPath) {
-    const rel = storeRelPath(relPath, "workspace file");
+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 Error(`"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to sync ${relPath}`);
+        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}`);
+}

package/dist/internal/workspace.d.ts

@@ -37,6 +37,15 @@ export declare function buildCloudMemorySection(agentName: string): string;
  * `syncWorkspaceToStore`), so the model has to be told where they are.
  */
 export declare function buildCloudWorkspaceSection(dir: string): string;
+/**
+ * Per-turn preamble for cloud `workspaceFiles` after they land on the
+ * session store prefix (see `syncSessionWorkspaceFiles`). Omitted when
+ * the sync did not land.
+ *
+ * Same shared Agent Store mount as authored seeds — the session path is
+ * replace-per-send / task-end wipe lifetime, not a separate mount ACL.
+ */
+export declare function buildCloudSessionWorkspaceSection(dir: string, relPaths: readonly string[]): string;
 /** Relative path of an agent-side tool script inside the session workspace. */
 export declare function agentToolScriptPath(toolName: string): string;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA8CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA6BR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CACX,MAAM,EACN,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CACjE,GACA,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,CAOR;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA8CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA6BR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CACX,MAAM,EACN,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CACjE,GACA,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/internal/workspace.js

@@ -50,6 +50,22 @@ export function buildCloudWorkspaceSection(dir) {
         `The agent's authored workspace files live at \`${dir}\` on this machine. Relative paths in your instructions that name these files resolve under that directory rather than your working directory. Read them with your normal file tools. The directory is shared across sessions, so copy a file into your working directory before editing it.`,
     ].join("\n");
 }
+/**
+ * Per-turn preamble for cloud `workspaceFiles` after they land on the
+ * session store prefix (see `syncSessionWorkspaceFiles`). Omitted when
+ * the sync did not land.
+ *
+ * Same shared Agent Store mount as authored seeds — the session path is
+ * replace-per-send / task-end wipe lifetime, not a separate mount ACL.
+ */
+export function buildCloudSessionWorkspaceSection(dir, relPaths) {
+    const listed = relPaths.map((path) => `\`${path}\``).join(", ");
+    return [
+        "## Session workspace files",
+        "",
+        `This turn's workspace files live at \`${dir}\` on this machine (${listed}). Read them with your normal file tools. They sit on the same shared Agent Store mount as authored workspace seeds; the session directory is replaced on the next send for this session, and task sessions remove it when they finish.`,
+    ].join("\n");
+}
 /** Relative path of an agent-side tool script inside the session workspace. */
 export function agentToolScriptPath(toolName) {
     return `.agent-serve/tools/${toolName}.sh`;