@cursor/july 0.1.102 → 0.1.103

package/dist/internal/tenant-slack/relay.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Relay-backed Slack posting for managed deployments.
+ *
+ * On AgentSDK v2 managed deployments the fork never receives a Slack token.
+ * The delivery envelope carries the matched automation's configured Slack
+ * **channel ids** only (`managedAutomation.slackChannels`, absent when the
+ * customer toggled "Send to Slack" off); each post goes through the control
+ * plane's Slack relay
+ * (`/internal/agent-serve/agent-sdk-slack-relay/:automationUuid`),
+ * authenticated with the pod's own `CURSOR_API_KEY`. The relay re-checks
+ * that the channel is configured on exactly that automation, renders the
+ * markdown, and posts as the Cursor Slack app with the customer's stored
+ * workspace token.
+ *
+ * INTERNAL: first-party multi-tenant deployment plumbing. Deliberately
+ * excluded from the published `@cursor/july` npm package (see the `files`
+ * whitelist); consumed by internal deployments via relative source imports.
+ */
+/**
+ * Path prefix of the backend relay route. Must match the mount in
+ * `backend/server/src/agentServe/agentServeEndpoints.ts`
+ * (`agentSdkSlackRelayRoutes`).
+ */
+export declare const AGENT_SDK_SLACK_RELAY_PATH_PREFIX = "/internal/agent-serve/agent-sdk-slack-relay";
+/** Mirrors the relay's body bound; longer summaries are truncated client-side. */
+export declare const AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS = 12000;
+/**
+ * Relay URL scoped to the source managed automation the delivery envelope
+ * attributed, so the relay checks the destination against exactly that
+ * automation's configured channels.
+ */
+export declare function relaySlackPostUrl(args: {
+    baseUrl: string;
+    automationUuid: string;
+}): string;
+export type RelaySlackPostResult = {
+    ok: true;
+    channel: string;
+    ts?: string;
+    permalink?: string;
+} | {
+    ok: false;
+    channel: string;
+    /** HTTP status from the relay, or 0 when the request never completed. */
+    status: number;
+    error: string;
+};
+export interface RelaySlackPostTarget {
+    relayBaseUrl: string;
+    apiKey: string;
+}
+/** Pod credential + external API base URL, or undefined off-platform. */
+export declare function resolveRelaySlackTarget(): RelaySlackPostTarget | undefined;
+/**
+ * Post one markdown message to one configured channel through the relay.
+ * Never throws: every failure is a `{ ok: false }` result so product code
+ * can log and continue (a Slack outage must not fail the review).
+ */
+export declare function postRelaySlackMessage(args: {
+    /** Source managed automation uuid from the delivery envelope. */
+    automationUuid: string;
+    /** Configured channel id (from `managedAutomation.slackChannels`). */
+    channel: string;
+    /** Markdown body. */
+    message: string;
+    /** Parent message ts to reply in a thread. */
+    threadTs?: string;
+    /** Test seam; defaults to the pod credential + external API base URL. */
+    resolve?: () => RelaySlackPostTarget | undefined;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<RelaySlackPostResult>;
+//# sourceMappingURL=relay.d.ts.map

package/dist/internal/tenant-slack/relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../../../src/internal/tenant-slack/relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,gDACC,CAAC;AAEhD,kFAAkF;AAClF,eAAO,MAAM,uCAAuC,QAAS,CAAC;AAI9D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAKT;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9D;IACE,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yEAAyE;AACzE,wBAAgB,uBAAuB,IAAI,oBAAoB,GAAG,SAAS,CAM1E;AAmBD;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,oBAAoB,GAAG,SAAS,CAAC;IACjD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAmEhC"}

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

@@ -0,0 +1,138 @@
+/**
+ * Relay-backed Slack posting for managed deployments.
+ *
+ * On AgentSDK v2 managed deployments the fork never receives a Slack token.
+ * The delivery envelope carries the matched automation's configured Slack
+ * **channel ids** only (`managedAutomation.slackChannels`, absent when the
+ * customer toggled "Send to Slack" off); each post goes through the control
+ * plane's Slack relay
+ * (`/internal/agent-serve/agent-sdk-slack-relay/:automationUuid`),
+ * authenticated with the pod's own `CURSOR_API_KEY`. The relay re-checks
+ * that the channel is configured on exactly that automation, renders the
+ * markdown, and posts as the Cursor Slack app with the customer's stored
+ * workspace token.
+ *
+ * INTERNAL: first-party multi-tenant deployment plumbing. Deliberately
+ * excluded from the published `@cursor/july` npm package (see the `files`
+ * whitelist); consumed by internal deployments via relative source imports.
+ */
+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 { cursorExternalApiUrl, resolveApiKeySync, } from "../cursor/credentials.js";
+/**
+ * Path prefix of the backend relay route. Must match the mount in
+ * `backend/server/src/agentServe/agentServeEndpoints.ts`
+ * (`agentSdkSlackRelayRoutes`).
+ */
+export const AGENT_SDK_SLACK_RELAY_PATH_PREFIX = "/internal/agent-serve/agent-sdk-slack-relay";
+/** Mirrors the relay's body bound; longer summaries are truncated client-side. */
+export const AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS = 12000;
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Relay URL scoped to the source managed automation the delivery envelope
+ * attributed, so the relay checks the destination against exactly that
+ * automation's configured channels.
+ */
+export function relaySlackPostUrl(args) {
+    const trimmed = args.baseUrl.endsWith("/")
+        ? args.baseUrl.slice(0, -1)
+        : args.baseUrl;
+    return `${trimmed}${AGENT_SDK_SLACK_RELAY_PATH_PREFIX}/${encodeURIComponent(args.automationUuid)}`;
+}
+/** Pod credential + external API base URL, or undefined off-platform. */
+export function resolveRelaySlackTarget() {
+    const resolved = resolveApiKeySync();
+    if (resolved === undefined) {
+        return undefined;
+    }
+    return { relayBaseUrl: cursorExternalApiUrl(), apiKey: resolved.apiKey };
+}
+function truncateMessage(message) {
+    if (message.length <= AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS) {
+        return message;
+    }
+    const marker = "\n\n_(truncated)_";
+    return `${message.slice(0, AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS - marker.length)}${marker}`;
+}
+function describeError(error) {
+    if (error instanceof Error) {
+        return error.name === "TimeoutError" || error.name === "AbortError"
+            ? "relay request timed out"
+            : error.message;
+    }
+    return String(error);
+}
+/**
+ * Post one markdown message to one configured channel through the relay.
+ * Never throws: every failure is a `{ ok: false }` result so product code
+ * can log and continue (a Slack outage must not fail the review).
+ */
+export function postRelaySlackMessage(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const channel = args.channel.trim();
+        if (channel === "") {
+            return { ok: false, channel, status: 0, error: "empty channel" };
+        }
+        const target = ((_a = args.resolve) !== null && _a !== void 0 ? _a : resolveRelaySlackTarget)();
+        if (target === undefined) {
+            return {
+                ok: false,
+                channel,
+                status: 0,
+                error: "no Cursor credential for the Slack relay",
+            };
+        }
+        const fetchImpl = (_b = args.fetchImpl) !== null && _b !== void 0 ? _b : fetch;
+        const url = relaySlackPostUrl({
+            baseUrl: target.relayBaseUrl,
+            automationUuid: args.automationUuid,
+        });
+        let response;
+        try {
+            response = yield fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${target.apiKey}`,
+                    "content-type": "application/json",
+                    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),
+            });
+        }
+        catch (error) {
+            return { ok: false, channel, status: 0, error: describeError(error) };
+        }
+        let body;
+        try {
+            body = yield response.json();
+        }
+        catch (_d) {
+            body = undefined;
+        }
+        const record = typeof body === "object" && body !== null && !Array.isArray(body)
+            ? body
+            : {};
+        if (!response.ok || record.ok !== true) {
+            return {
+                ok: false,
+                channel,
+                status: response.status,
+                error: typeof record.error === "string" && record.error !== ""
+                    ? record.error
+                    : `relay responded ${response.status}`,
+            };
+        }
+        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/testing/scm-continuation-fixtures.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GitLab / Bitbucket continuation fixtures shared by the two continuation
+ * vocabulary copies — `internal/continuation-identity.ts` (July) and the
+ * control plane's `agentSdkConversationIdentity.ts` (server-shared). Both
+ * suites import this one module, so a payload shape or key format that only
+ * one copy understands fails CI on the other side.
+ *
+ * Pure data: no imports, so the server-shared suite can load it by relative
+ * path without pulling `@cursor/july` into the control plane.
+ */
+export interface ScmContinuationFixture {
+    name: string;
+    kind: "gitlab" | "bitbucket";
+    /** Conversation type the channel's `<kind>.<type>/v2` selector names. */
+    type: "gitlab-mr" | "bitbucket-pr";
+    /**
+     * Mailbox event name. Bitbucket Data Center deliveries arrive with their
+     * Cloud-normalized key (`pr:opened` → `pullrequest:created`) next to the
+     * raw DC payload.
+     */
+    eventType: string;
+    payload: Record<string, unknown>;
+    /** `cont:` key, or `undefined` when the delivery stamps `evt:`. */
+    expectedKey: string | undefined;
+}
+export interface ScmDefaultSelectorFixture {
+    kind: "gitlab" | "bitbucket";
+    eventTypes: readonly string[];
+    expected: string;
+}
+export declare const SCM_CONTINUATION_FIXTURES: readonly ScmContinuationFixture[];
+export declare const SCM_DEFAULT_SELECTOR_FIXTURES: readonly ScmDefaultSelectorFixture[];
+//# sourceMappingURL=scm-continuation-fixtures.d.ts.map

package/dist/internal/testing/scm-continuation-fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scm-continuation-fixtures.d.ts","sourceRoot":"","sources":["../../../src/internal/testing/scm-continuation-fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC7B,yEAAyE;IACzE,IAAI,EAAE,WAAW,GAAG,cAAc,CAAC;IACnC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC7B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAqCD,eAAO,MAAM,yBAAyB,EAAE,SAAS,sBAAsB,EAgMtE,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,SAAS,yBAAyB,EAuB3E,CAAC"}

package/dist/internal/testing/scm-continuation-fixtures.js

@@ -0,0 +1,253 @@
+/**
+ * GitLab / Bitbucket continuation fixtures shared by the two continuation
+ * vocabulary copies — `internal/continuation-identity.ts` (July) and the
+ * control plane's `agentSdkConversationIdentity.ts` (server-shared). Both
+ * suites import this one module, so a payload shape or key format that only
+ * one copy understands fails CI on the other side.
+ *
+ * Pure data: no imports, so the server-shared suite can load it by relative
+ * path without pulling `@cursor/july` into the control plane.
+ */
+const GITLAB_PROJECT = {
+    id: 1234,
+    name: "api",
+    path_with_namespace: "Acme/platform/api",
+    web_url: "https://gitlab.com/Acme/platform/api",
+    default_branch: "main",
+};
+const GITLAB_MERGE_REQUEST = {
+    id: 9001,
+    iid: 42,
+    title: "Add widgets",
+    state: "opened",
+    source_branch: "feature/widgets",
+    target_branch: "main",
+    url: "https://gitlab.com/Acme/platform/api/-/merge_requests/42",
+    last_commit: { id: "0123456789abcdef0123456789abcdef01234567" },
+};
+const BITBUCKET_CLOUD_REPOSITORY = {
+    type: "repository",
+    full_name: "acme/widgets",
+    name: "widgets",
+    uuid: "{5f2d1d5e-6d66-4f5b-9d3e-1b6e5b1c2f3a}",
+    workspace: { slug: "acme", uuid: "{a4f1c5d0-1111-4a2b-8c3d-9e0f1a2b3c4d}" },
+    links: { html: { href: "https://bitbucket.org/acme/widgets" } },
+};
+const BITBUCKET_DC_REPOSITORY = {
+    slug: "widgets",
+    id: 17,
+    name: "widgets",
+    project: { key: "ACME", id: 3, name: "Acme" },
+};
+export const SCM_CONTINUATION_FIXTURES = [
+    {
+        name: "gitlab merge_request open",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "merge_request",
+        payload: {
+            object_kind: "merge_request",
+            event_type: "merge_request",
+            user: { id: 7, username: "alice", name: "Alice" },
+            project: GITLAB_PROJECT,
+            object_attributes: Object.assign(Object.assign({}, GITLAB_MERGE_REQUEST), { action: "open" }),
+        },
+        expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+    },
+    {
+        name: "gitlab merge_request update (new commits)",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "merge_request",
+        payload: {
+            object_kind: "merge_request",
+            event_type: "merge_request",
+            user: { id: 7, username: "alice", name: "Alice" },
+            project: GITLAB_PROJECT,
+            object_attributes: Object.assign(Object.assign({}, GITLAB_MERGE_REQUEST), { action: "update", oldrev: "fedcba9876543210fedcba9876543210fedcba98" }),
+        },
+        expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+    },
+    {
+        name: "gitlab note on merge request",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "note",
+        payload: {
+            object_kind: "note",
+            event_type: "note",
+            user: { id: 8, username: "bob", name: "Bob" },
+            project: GITLAB_PROJECT,
+            object_attributes: {
+                id: 501,
+                note: "Looks good",
+                noteable_type: "MergeRequest",
+                noteable_id: 9001,
+            },
+            merge_request: GITLAB_MERGE_REQUEST,
+        },
+        expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+    },
+    {
+        name: "gitlab note on issue",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "note",
+        payload: {
+            object_kind: "note",
+            event_type: "note",
+            user: { id: 8, username: "bob", name: "Bob" },
+            project: GITLAB_PROJECT,
+            object_attributes: {
+                id: 502,
+                note: "Tracking",
+                noteable_type: "Issue",
+                noteable_id: 300,
+            },
+            issue: { id: 300, iid: 9, title: "Bug" },
+        },
+        expectedKey: undefined,
+    },
+    {
+        name: "gitlab pipeline attached to a merge request",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "pipeline",
+        payload: {
+            object_kind: "pipeline",
+            project: GITLAB_PROJECT,
+            object_attributes: { id: 77, status: "success", sha: "0123456789ab" },
+            merge_request: { iid: 42, id: 9001, title: "Add widgets" },
+        },
+        expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+    },
+    {
+        name: "gitlab pipeline without a merge request",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "pipeline",
+        payload: {
+            object_kind: "pipeline",
+            project: GITLAB_PROJECT,
+            object_attributes: { id: 78, status: "success", sha: "0123456789ab" },
+            merge_request: null,
+        },
+        expectedKey: undefined,
+    },
+    {
+        name: "gitlab push",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "push",
+        payload: {
+            object_kind: "push",
+            event_name: "push",
+            ref: "refs/heads/main",
+            project: GITLAB_PROJECT,
+            commits: [],
+        },
+        expectedKey: undefined,
+    },
+    {
+        name: "bitbucket cloud pullrequest:created",
+        kind: "bitbucket",
+        type: "bitbucket-pr",
+        eventType: "pullrequest:created",
+        payload: {
+            repository: BITBUCKET_CLOUD_REPOSITORY,
+            actor: { display_name: "Alice", uuid: "{u-1}" },
+            pullrequest: {
+                id: 7,
+                title: "Add widgets",
+                state: "OPEN",
+                source: {
+                    branch: { name: "feature/widgets" },
+                    commit: { hash: "0123456789ab" },
+                },
+                destination: { branch: { name: "main" }, commit: { hash: "fedcba98" } },
+                links: {
+                    html: { href: "https://bitbucket.org/acme/widgets/pull-requests/7" },
+                },
+            },
+        },
+        expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+    },
+    {
+        name: "bitbucket data center pr:opened (normalized to pullrequest:created)",
+        kind: "bitbucket",
+        type: "bitbucket-pr",
+        eventType: "pullrequest:created",
+        payload: {
+            eventKey: "pr:opened",
+            date: "2026-09-01T12:00:00+0000",
+            actor: { name: "alice", displayName: "Alice", id: 1 },
+            pullRequest: {
+                id: 7,
+                title: "Add widgets",
+                state: "OPEN",
+                open: true,
+                fromRef: {
+                    id: "refs/heads/feature/widgets",
+                    displayId: "feature/widgets",
+                    latestCommit: "0123456789ab",
+                    repository: BITBUCKET_DC_REPOSITORY,
+                },
+                toRef: {
+                    id: "refs/heads/main",
+                    displayId: "main",
+                    latestCommit: "fedcba98",
+                    repository: BITBUCKET_DC_REPOSITORY,
+                },
+            },
+        },
+        expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+    },
+    {
+        name: "bitbucket cloud pullrequest:comment_created",
+        kind: "bitbucket",
+        type: "bitbucket-pr",
+        eventType: "pullrequest:comment_created",
+        payload: {
+            repository: BITBUCKET_CLOUD_REPOSITORY,
+            actor: { display_name: "Bob", uuid: "{u-2}" },
+            pullrequest: { id: 7, title: "Add widgets", state: "OPEN" },
+            comment: { id: 11, content: { raw: "Looks good" } },
+        },
+        expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+    },
+    {
+        name: "bitbucket cloud repo:push",
+        kind: "bitbucket",
+        type: "bitbucket-pr",
+        eventType: "repo:push",
+        payload: {
+            repository: BITBUCKET_CLOUD_REPOSITORY,
+            actor: { display_name: "Alice", uuid: "{u-1}" },
+            push: { changes: [] },
+        },
+        expectedKey: undefined,
+    },
+];
+export const SCM_DEFAULT_SELECTOR_FIXTURES = [
+    { kind: "gitlab", eventTypes: ["merge_request"], expected: "gitlab.mr/v2" },
+    {
+        kind: "gitlab",
+        eventTypes: ["merge_request", "note"],
+        expected: "gitlab.mr/v2",
+    },
+    {
+        kind: "gitlab",
+        eventTypes: ["merge_request", "push"],
+        expected: "gitlab.none/v2",
+    },
+    {
+        kind: "bitbucket",
+        eventTypes: ["pullrequest:created", "pullrequest:updated"],
+        expected: "bitbucket.pr/v2",
+    },
+    {
+        kind: "bitbucket",
+        eventTypes: ["pullrequest:created", "repo:push"],
+        expected: "bitbucket.none/v2",
+    },
+];

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

@@ -0,0 +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.
+ */
+import { type FileSink } from "../files.js";
+import type { SeedFile } from "../types.js";
+/**
+ * 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>;
+//# 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;;;;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"}

package/dist/internal/workspace-sync.js

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+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";
+/**
+ * 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(seedRelPath(seed.relativePath), workspacePrefix), yield readFile(seed.sourcePath));
+        }
+        yield mirrorToStore({ sink: args.sink, prefix: workspacePrefix, desired });
+    });
+}
+/**
+ * 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.
+ */
+function seedRelPath(relPath) {
+    const rel = storeRelPath(relPath, "workspace file");
+    if (rel.split("/", 1)[0] === MEMORY_DIR_NAME) {
+        throw new Error(`"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to sync ${relPath}`);
+    }
+    return rel;
+}

package/dist/internal/workspace.d.ts

@@ -30,6 +30,13 @@ export interface MaterializeWorkspaceOptions {
  * deployments: cloud VMs read the memory journal from the store mount.
  */
 export declare function buildCloudMemorySection(agentName: string): string;
+/**
+ * First-turn preamble section for cloud-runtime sessions with authored
+ * `agent/sandbox/workspace/**` seeds. Cloud VMs get no materialized
+ * workspace; the seeds are synced onto the store mount instead (see
+ * `syncWorkspaceToStore`), so the model has to be told where they are.
+ */
+export declare function buildCloudWorkspaceSection(dir: 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,+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,+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

@@ -37,6 +37,19 @@ export function buildCloudMemorySection(agentName) {
         `The cross-session memory journal (the \`memory/\` directory your instructions may reference) lives at \`${dir}\` on this machine — read \`${dir}/journal.jsonl\` with your normal file tools.`,
     ].join("\n");
 }
+/**
+ * First-turn preamble section for cloud-runtime sessions with authored
+ * `agent/sandbox/workspace/**` seeds. Cloud VMs get no materialized
+ * workspace; the seeds are synced onto the store mount instead (see
+ * `syncWorkspaceToStore`), so the model has to be told where they are.
+ */
+export function buildCloudWorkspaceSection(dir) {
+    return [
+        "## Workspace files",
+        "",
+        `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");
+}
 /** Relative path of an agent-side tool script inside the session workspace. */
 export function agentToolScriptPath(toolName) {
     return `.agent-serve/tools/${toolName}.sh`;