@cursor/july 0.1.39 → 0.1.41

package/dist/internal/cursor-event-relay.d.ts

@@ -48,6 +48,34 @@ export type CursorScmPullRequestMeta = {
     baseRef?: string;
     baseSha?: string;
 };
+/** PR ref on a Checks / Actions webhook object. */
+export type CursorScmCiPullRequestMeta = {
+    number: number;
+    url?: string;
+};
+export type CursorScmCiAppMeta = {
+    slug?: string;
+    name?: string;
+};
+/** Shared Checks / Actions fields. `id` + `headSha` satisfy the channel Zod schemas. */
+type CursorScmCiBaseMeta = {
+    id: number;
+    headSha: string;
+    status?: string;
+    conclusion?: string | null;
+    htmlUrl?: string;
+    app?: CursorScmCiAppMeta;
+    pullRequests: CursorScmCiPullRequestMeta[];
+};
+export type CursorScmCheckRunMeta = CursorScmCiBaseMeta & {
+    name?: string;
+    checkSuiteId?: number;
+};
+export type CursorScmCheckSuiteMeta = CursorScmCiBaseMeta;
+export type CursorScmWorkflowRunMeta = CursorScmCiBaseMeta & {
+    name?: string;
+    workflowId?: number;
+};
 /** One event delivered by `GET /v0/scm-events` (metadata only). */
 export interface CursorScmEvent {
     offset: string;
@@ -72,6 +100,12 @@ export interface CursorScmEvent {
      * Zod-valid `issue_comment` / `pull_request_review_comment` webhook body.
      */
     comment?: CursorScmCommentMeta;
+    /** `check_run` snapshot; enough to stub `onCheckRun`. */
+    checkRun?: CursorScmCheckRunMeta;
+    /** `check_suite` snapshot; enough to stub `onCheckSuite`. */
+    checkSuite?: CursorScmCheckSuiteMeta;
+    /** `workflow_run` snapshot; enough to stub `onWorkflowRun`. */
+    workflowRun?: CursorScmWorkflowRunMeta;
     /** GitHub-side event time from the payload, when present. */
     occurredAtMs?: number;
 }
@@ -103,12 +137,20 @@ export declare function formatCursorScmEventLog(event: {
     occurredAtMs?: number;
     deliveryId?: string;
 }): string;
+/** Relay log suffix for one fan-out target, including parse errors on 4xx. */
+export declare function formatCursorScmDispatchOutcome(target: {
+    slug: string;
+    status: number;
+    body: unknown;
+}): string;
 /**
  * Minimal GitHub webhook body from an SCM-events metadata envelope.
  * When `pullRequest` has title + head/base refs+shas, emits a Zod-valid
  * `pull_request` object for `onPullRequest`; otherwise identity-only stubs.
  * When `comment` is present, emits a Zod-valid `comment` object so relayed
  * `issue_comment` / `pull_request_review_comment` deliveries dispatch.
+ * When a CI snapshot is present, emits `check_run` / `check_suite` /
+ * `workflow_run` so those typed hooks parse on the `--cursor-events` path.
  */
 export declare function scmMetadataToGitHubPayload(event: {
     repo: string;
@@ -117,6 +159,9 @@ export declare function scmMetadataToGitHubPayload(event: {
     prUrl?: string;
     pullRequest?: CursorScmPullRequestMeta;
     comment?: CursorScmCommentMeta;
+    checkRun?: CursorScmCheckRunMeta;
+    checkSuite?: CursorScmCheckSuiteMeta;
+    workflowRun?: CursorScmWorkflowRunMeta;
 }): Record<string, unknown>;
 /**
  * GitHub SCM-events relay: a thin {@link CursorRelayCore} adapter. Consumers

package/dist/internal/cursor-event-relay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-event-relay.d.ts","sourceRoot":"","sources":["../../src/internal/cursor-event-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAGL,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AASD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,2CAA2C;IAC3C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAgBT;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAChC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2G1B;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAUf,OAAO,CAAC,QAAQ,CAAC,OAAO;IATpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkC;IACvD;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IAExD,YAA6B,OAAO,EAAE,uBAAuB,EAwD5D;IAED;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAatB,KAAK,IAAI,IAAI,CAEZ;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1B;CACF"}
+{"version":3,"file":"cursor-event-relay.d.ts","sourceRoot":"","sources":["../../src/internal/cursor-event-relay.ts"],"names":[],"mappings":"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"}

package/dist/internal/cursor-event-relay.js

@@ -36,22 +36,44 @@ export function formatCursorScmEventLog(event) {
     const delivery = (_a = event.deliveryId) !== null && _a !== void 0 ? _a : "no delivery id";
     return `${event.eventName}${action} on ${pr} received=${received}${occurred} (${delivery})`;
 }
+/** Relay log suffix for one fan-out target, including parse errors on 4xx. */
+export function formatCursorScmDispatchOutcome(target) {
+    const slug = target.slug === "" ? "default" : target.slug;
+    if (target.status < 400) {
+        return `${slug}:${target.status}`;
+    }
+    const error = readDispatchError(target.body);
+    return error === undefined
+        ? `${slug}:${target.status}`
+        : `${slug}:${target.status} ${error}`;
+}
+function readDispatchError(body) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    if (!("error" in body))
+        return undefined;
+    const error = body.error;
+    return typeof error === "string" && error !== "" ? error : undefined;
+}
 /**
  * Minimal GitHub webhook body from an SCM-events metadata envelope.
  * When `pullRequest` has title + head/base refs+shas, emits a Zod-valid
  * `pull_request` object for `onPullRequest`; otherwise identity-only stubs.
  * When `comment` is present, emits a Zod-valid `comment` object so relayed
  * `issue_comment` / `pull_request_review_comment` deliveries dispatch.
+ * When a CI snapshot is present, emits `check_run` / `check_suite` /
+ * `workflow_run` so those typed hooks parse on the `--cursor-events` path.
  */
 export function scmMetadataToGitHubPayload(event) {
     var _a, _b, _c;
+    var _d, _e, _f, _g, _h;
     const slash = event.repo.indexOf("/");
     const owner = slash === -1 ? "" : event.repo.slice(0, slash);
     const name = slash === -1 ? event.repo : event.repo.slice(slash + 1);
     const repoUrl = `https://github.com/${event.repo}`;
     const prMeta = event.pullRequest;
-    const prNumber = (_a = prMeta === null || prMeta === void 0 ? void 0 : prMeta.number) !== null && _a !== void 0 ? _a : event.prNumber;
-    const prUrl = (_c = (_b = prMeta === null || prMeta === void 0 ? void 0 : prMeta.url) !== null && _b !== void 0 ? _b : event.prUrl) !== null && _c !== void 0 ? _c : (prNumber !== undefined ? `${repoUrl}/pull/${prNumber}` : undefined);
+    const prNumber = (_d = prMeta === null || prMeta === void 0 ? void 0 : prMeta.number) !== null && _d !== void 0 ? _d : event.prNumber;
+    const prUrl = (_f = (_e = prMeta === null || prMeta === void 0 ? void 0 : prMeta.url) !== null && _e !== void 0 ? _e : event.prUrl) !== null && _f !== void 0 ? _f : (prNumber !== undefined ? `${repoUrl}/pull/${prNumber}` : undefined);
     const payload = {
         repository: {
             full_name: event.repo,
@@ -96,6 +118,20 @@ export function scmMetadataToGitHubPayload(event) {
         }
         payload.comment = comment;
     }
+    const checkPullRequests = stubGitHubCiPullRequests({
+        snapshot: (_h = (_g = (_a = event.checkRun) === null || _a === void 0 ? void 0 : _a.pullRequests) !== null && _g !== void 0 ? _g : (_b = event.checkSuite) === null || _b === void 0 ? void 0 : _b.pullRequests) !== null && _h !== void 0 ? _h : (_c = event.workflowRun) === null || _c === void 0 ? void 0 : _c.pullRequests,
+        prNumber,
+        prUrl,
+    });
+    if (event.checkRun !== undefined) {
+        payload.check_run = stubGitHubCheckRun(event.checkRun, checkPullRequests);
+    }
+    if (event.checkSuite !== undefined) {
+        payload.check_suite = stubGitHubCheckSuite(event.checkSuite, checkPullRequests);
+    }
+    if (event.workflowRun !== undefined) {
+        payload.workflow_run = stubGitHubWorkflowRun(event.workflowRun, checkPullRequests);
+    }
     const title = prMeta === null || prMeta === void 0 ? void 0 : prMeta.title;
     const headRef = prMeta === null || prMeta === void 0 ? void 0 : prMeta.headRef;
     const headSha = prMeta === null || prMeta === void 0 ? void 0 : prMeta.headSha;
@@ -143,6 +179,64 @@ export function scmMetadataToGitHubPayload(event) {
     }
     return payload;
 }
+function stubGitHubCiPullRequests(input) {
+    if (input.snapshot !== undefined && input.snapshot.length > 0) {
+        return input.snapshot.map((pr) => (Object.assign({ number: pr.number }, (pr.url === undefined ? {} : { html_url: pr.url }))));
+    }
+    if (input.prNumber === undefined)
+        return [];
+    return [
+        Object.assign({ number: input.prNumber }, (input.prUrl === undefined ? {} : { html_url: input.prUrl })),
+    ];
+}
+function stubGitHubCiApp(app) {
+    if (app === undefined)
+        return undefined;
+    const out = {};
+    if (app.slug !== undefined)
+        out.slug = app.slug;
+    if (app.name !== undefined)
+        out.name = app.name;
+    return out;
+}
+function stubGitHubCiBase(meta, pullRequests) {
+    const object = {
+        id: meta.id,
+        head_sha: meta.headSha,
+    };
+    if (meta.status !== undefined)
+        object.status = meta.status;
+    if (meta.conclusion !== undefined)
+        object.conclusion = meta.conclusion;
+    if (meta.htmlUrl !== undefined)
+        object.html_url = meta.htmlUrl;
+    const app = stubGitHubCiApp(meta.app);
+    if (app !== undefined)
+        object.app = app;
+    if (pullRequests.length > 0)
+        object.pull_requests = pullRequests;
+    return object;
+}
+function stubGitHubCheckRun(meta, pullRequests) {
+    const object = stubGitHubCiBase(meta, pullRequests);
+    if (meta.name !== undefined)
+        object.name = meta.name;
+    if (meta.checkSuiteId !== undefined) {
+        object.check_suite = { id: meta.checkSuiteId };
+    }
+    return object;
+}
+function stubGitHubCheckSuite(meta, pullRequests) {
+    return stubGitHubCiBase(meta, pullRequests);
+}
+function stubGitHubWorkflowRun(meta, pullRequests) {
+    const object = stubGitHubCiBase(meta, pullRequests);
+    if (meta.name !== undefined)
+        object.name = meta.name;
+    if (meta.workflowId !== undefined)
+        object.workflow_id = meta.workflowId;
+    return object;
+}
 /**
  * GitHub SCM-events relay: a thin {@link CursorRelayCore} adapter. Consumers
  * keep the same `new CursorEventRelay(options).start()/.stop()` surface.

package/dist/internal/deploy-client.js

@@ -442,7 +442,7 @@ function mapErrorResponse(response, bodyText, context) {
         case 401:
             return new DeployApiError("The Cursor API key was rejected. Run `agent-sdk login` again or update CURSOR_API_KEY.", 401);
         case 403:
-            return new DeployApiError(`${serverError !== null && serverError !== void 0 ? serverError : "Not authorized"} — deploying needs team-admin permission and the cloud-agent entitlement on that team.`, 403);
+            return new DeployApiError(`${serverError !== null && serverError !== void 0 ? serverError : "Not authorized"} — deploying needs team membership and the cloud-agent entitlement on that team.`, 403);
         case 404: {
             // Fastify's route-not-found envelope means we hit the wrong host
             // (api2 vs api.cursor.com), not a missing deployment / closed gate.

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

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/internal/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiBH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EASrB,KAAK,UAAU,EAuBhB,MAAM,aAAa,CAAC;AA2BrB,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3E;AAmBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASrE;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,EAAE,CAAC,CA2B1B;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAoBzD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAAuB,GAAG;IACjC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CACtB,GACL,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAgBzD;AAWD,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,CAIrC,CAAC;AAEH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,YAAY,CAAC,CAiEvB;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAElE;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAOnE;AA2pBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB3E;AAgxBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CA6InE"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/internal/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiBH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAUrB,KAAK,UAAU,EAuBhB,MAAM,aAAa,CAAC;AA2BrB,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3E;AAmBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASrE;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,EAAE,CAAC,CA2B1B;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CA6BzD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAAuB,GAAG;IACjC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CACtB,GACL,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAgBzD;AAWD,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,CAIrC,CAAC;AAEH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,YAAY,CAAC,CAiEvB;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAElE;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAOnE;AAkrBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB3E;AAgxBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CAiJnE"}

package/dist/internal/discovery.js

@@ -120,11 +120,18 @@ export function loadAgentProjects(rootDir_1) {
             throw new Error(`No agent projects found directly under ${resolved}. Each agent should be a subdirectory with its own agent/ directory (or flat-layout markers).`);
         }
         const results = [];
+        // Storage namespaces (session mirror, host kv, durable-session ledger)
+        // key on the project NAME, not the mount slug — two co-hosted agents
+        // sharing a name would silently share sessions and coordination state.
+        const slugByName = new Map();
         for (const child of children) {
-            results.push({
-                slug: child.slug,
-                project: yield loadAgentProject(child.dir, options),
-            });
+            const project = yield loadAgentProject(child.dir, options);
+            const priorSlug = slugByName.get(project.name);
+            if (priorSlug !== undefined) {
+                throw new Error(`Duplicate agent name "${project.name}" under ${resolved}: agents "${priorSlug}" and "${child.slug}" both resolve to it (package.json "name", or the directory name when unset). Co-hosted agents must have distinct names — their storage and session namespaces key on the name.`);
+            }
+            slugByName.set(project.name, child.slug);
+            results.push({ slug: child.slug, project });
         }
         return results;
     });
@@ -306,6 +313,7 @@ function loadAgent(ctx, agentDir, options) {
             };
         const hosting = resolveHosting(ctx, agentDir, config === null || config === void 0 ? void 0 : config.hosting);
         const concurrency = resolveConcurrency(ctx, agentDir, config === null || config === void 0 ? void 0 : config.concurrency);
+        const serving = resolveServing(ctx, agentDir, config === null || config === void 0 ? void 0 : config.serving);
         if (runtime === "cloud") {
             warnCloudRuntimeLimitations(ctx, agentDir, {
                 agentTools: tools.filter((tool) => tool.execution === "agent").length,
@@ -326,6 +334,7 @@ function loadAgent(ctx, agentDir, options) {
             local,
             hosting,
             concurrency,
+            serving,
             tools,
             skills,
             connections,
@@ -334,6 +343,22 @@ function loadAgent(ctx, agentDir, options) {
         };
     });
 }
+/**
+ * Validate the authored serving mode. An unrecognized value is an error
+ * diagnostic and falls back to undefined (resident) — a typo must not
+ * silently opt an agent into (or out of) ledger coordination.
+ */
+function resolveServing(ctx, agentDir, serving) {
+    if (serving === undefined || serving === "resident" || serving === "ledger") {
+        return serving;
+    }
+    ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message: `serving must be "resident" or "ledger"; got ${JSON.stringify(serving)}.`,
+    });
+    return undefined;
+}
 /** Absolute harness cwd parent, or undefined when unset / blank. */
 function resolveAgentCwd(ctx, authored) {
     if (authored === undefined) {
@@ -376,7 +401,7 @@ function resolveHosting(ctx, agentDir, hosting) {
             warn(`hosting.secretNames: ${nameError}`);
         }
         else if (isReservedSecretName(name)) {
-            warn(`hosting.secretNames: ${JSON.stringify(name)} is platform-managed (CURSOR_* / Cursor-hosted storage) and injected automatically; omit it from secretNames.`);
+            warn(`hosting.secretNames: ${JSON.stringify(name)} is platform-managed (CURSOR_* / reserved hosted-storage names); omit it from secretNames.`);
         }
     }
     return Object.assign(Object.assign({}, (hosting.egressDomains === undefined
@@ -1525,11 +1550,14 @@ export function projectInfo(project) {
         })), skills: agent.skills.map((skill) => ({
             name: skill.name,
             description: skill.description,
-        })), connections: agent.connections.map((connection) => ({
+        })), connections: agent.connections.map((connection) => { var _a; return ({
             name: connection.name,
             transport: connectionTransportLabel(connection.transport),
             hostOnly: connection.hostOnly,
-        })), subagents: agent.subagents.map((subagent) => ({
+            cursorAccountServers: "cursorAccount" in connection.transport
+                ? ((_a = connection.transport.servers) !== null && _a !== void 0 ? _a : "*")
+                : undefined,
+        }); }), subagents: agent.subagents.map((subagent) => ({
             name: subagent.name,
             description: subagent.description,
             model: subagent.model,

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

@@ -1 +1 @@
-{"version":3,"file":"distribution.d.ts","sourceRoot":"","sources":["../../src/internal/distribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,sEAAsE;AACtE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,WAAW,cAAc,CAAC;AACvC,eAAO,MAAM,UAAU,EAAE,MAA2B,CAAC;AACrD,eAAO,MAAM,gBAAgB,EAAE,MAAiC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAA+B,CAAC;AAc/D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,kEAAkE;AAClE,wBAAgB,cAAc,IAAI,MAAM,CAOvC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAC/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAuBzC,CAAC"}
+{"version":3,"file":"distribution.d.ts","sourceRoot":"","sources":["../../src/internal/distribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,sEAAsE;AACtE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,WAAW,cAAc,CAAC;AACvC,eAAO,MAAM,UAAU,EAAE,MAA2B,CAAC;AACrD,eAAO,MAAM,gBAAgB,EAAE,MAAiC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAA+B,CAAC;AAc/D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,kEAAkE;AAClE,wBAAgB,cAAc,IAAI,MAAM,CAOvC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAC/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAyBzC,CAAC"}

package/dist/internal/distribution.js

@@ -92,8 +92,10 @@ export const AUTHORING_ENTRY_FILES = [
     ["evals/loaders", "evals/loaders.js"],
     ["ab", "ab.js"],
     ["artifacts", "artifacts.js"],
+    ["kv", "kv.js"],
+    ["kv/memory", "kv/memory-kv.js"],
+    ["ledger", "ledger.js"],
     ["storage", "storage.js"],
     ["storage/file-kv", "storage-backends/file-kv.js"],
-    ["storage/postgres-kv", "storage-backends/postgres-kv.js"],
     ["storage/cursor-hosted", "storage-backends/cursor-hosted.js"],
 ];

package/dist/internal/durable-session-store.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Durable-session store resolution.
+ *
+ * Two APIs, one backend: `defineStorage` is the **storage API** (agent
+ * state — session records, event chunks, author KV), and the session
+ * ledger is the **durable session API** (session identity, leases,
+ * fenced commits). The ledger consumes {@link SessionLedgerKv} — exactly
+ * the three CAS methods it uses, nothing more; this module adapts a
+ * storage backend's `cas` group into that interface, so a deployment's
+ * one authored backend serves both APIs by default.
+ *
+ * Calls go straight at the config's methods — NOT through the
+ * StorageCoordinator: the coordinator's queue is bounded, serialized, and
+ * at-most-once (mirror semantics), while ledger CAS calls are the
+ * correctness path and must observe their own results synchronously.
+ */
+import type { SessionLedgerKv } from "../ledger/session-ledger.js";
+import { type StorageConfig } from "../storage.js";
+export interface StorageCasKvArgs {
+    agentName: string;
+    projectRoot: string;
+}
+/**
+ * Adapt a storage backend's `cas` group into the ledger's KV interface.
+ * Throws when the backend does not implement `cas` — the caller turns
+ * that into the fail-fast startup error for `serving: "ledger"`. Every
+ * call carries a `reason: "coordination"` {@link StorageContext}.
+ */
+export declare function storageCasKv(config: StorageConfig, args: StorageCasKvArgs): SessionLedgerKv;
+/**
+ * The one place the ledger's physical namespace is minted:
+ * `agentkit/v1/<agent>/durable-session/` — the {@link STORAGE_KEY_ROOT}
+ * conventions with the agent segment encoded like every other
+ * caller-controlled segment. The ledger itself never sees this string;
+ * it speaks bare `session/…` / `ledger/…` keys against a handle that
+ * {@link namespacedKv} has already scoped.
+ */
+export declare function ledgerKeyPrefix(agentName: string): string;
+/**
+ * Scope a raw store handle under a namespace, prepending it to every
+ * key on the way in. Applied exactly once, where the engine constructs
+ * the ledger's store handle — the same conceptual boundary where
+ * `host.kv` gets its agent scoping. Internal: not part of the public kv
+ * interface, and callers (including the explicit `durableSessionStore`
+ * override) always supply the raw store — they never write prefixes.
+ */
+export declare function namespacedKv(store: SessionLedgerKv, namespace: string): SessionLedgerKv;
+//# sourceMappingURL=durable-session-store.d.ts.map

package/dist/internal/durable-session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-session-store.d.ts","sourceRoot":"","sources":["../../src/internal/durable-session-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GACrB,eAAe,CAuBjB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,eAAe,CAOjB"}

package/dist/internal/durable-session-store.js

@@ -0,0 +1,86 @@
+/**
+ * Durable-session store resolution.
+ *
+ * Two APIs, one backend: `defineStorage` is the **storage API** (agent
+ * state — session records, event chunks, author KV), and the session
+ * ledger is the **durable session API** (session identity, leases,
+ * fenced commits). The ledger consumes {@link SessionLedgerKv} — exactly
+ * the three CAS methods it uses, nothing more; this module adapts a
+ * storage backend's `cas` group into that interface, so a deployment's
+ * one authored backend serves both APIs by default.
+ *
+ * Calls go straight at the config's methods — NOT through the
+ * StorageCoordinator: the coordinator's queue is bounded, serialized, and
+ * at-most-once (mirror semantics), while ledger CAS calls are the
+ * correctness path and must observe their own results synchronously.
+ */
+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 { keySegment, STORAGE_KEY_ROOT, } from "../storage.js";
+/**
+ * Adapt a storage backend's `cas` group into the ledger's KV interface.
+ * Throws when the backend does not implement `cas` — the caller turns
+ * that into the fail-fast startup error for `serving: "ledger"`. Every
+ * call carries a `reason: "coordination"` {@link StorageContext}.
+ */
+export function storageCasKv(config, args) {
+    const ctx = {
+        agentName: args.agentName,
+        projectRoot: args.projectRoot,
+        reason: "coordination",
+    };
+    const { cas } = config;
+    if (cas === undefined) {
+        throw new Error("storageCasKv: the storage backend does not implement the cas group (conditional writes)");
+    }
+    return {
+        getWithVersion(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield cas.getWithVersion(key, ctx);
+            });
+        },
+        putIfAbsent(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield cas.putIfAbsent(key, value, ctx);
+            });
+        },
+        putIfVersion(key, value, expectedVersion) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield cas.putIfVersion(key, value, expectedVersion, ctx);
+            });
+        },
+    };
+}
+/**
+ * The one place the ledger's physical namespace is minted:
+ * `agentkit/v1/<agent>/durable-session/` — the {@link STORAGE_KEY_ROOT}
+ * conventions with the agent segment encoded like every other
+ * caller-controlled segment. The ledger itself never sees this string;
+ * it speaks bare `session/…` / `ledger/…` keys against a handle that
+ * {@link namespacedKv} has already scoped.
+ */
+export function ledgerKeyPrefix(agentName) {
+    return `${STORAGE_KEY_ROOT}/${keySegment(agentName)}/durable-session/`;
+}
+/**
+ * Scope a raw store handle under a namespace, prepending it to every
+ * key on the way in. Applied exactly once, where the engine constructs
+ * the ledger's store handle — the same conceptual boundary where
+ * `host.kv` gets its agent scoping. Internal: not part of the public kv
+ * interface, and callers (including the explicit `durableSessionStore`
+ * override) always supply the raw store — they never write prefixes.
+ */
+export function namespacedKv(store, namespace) {
+    return {
+        getWithVersion: (key) => store.getWithVersion(namespace + key),
+        putIfAbsent: (key, value) => store.putIfAbsent(namespace + key, value),
+        putIfVersion: (key, value, expectedVersion) => store.putIfVersion(namespace + key, value, expectedVersion),
+    };
+}

package/dist/internal/hosting.d.ts

@@ -14,7 +14,7 @@ export declare const MAX_SECRETS = 32;
 export declare const MAX_SECRET_VALUE_BYTES = 4096;
 /** Max secret name length. */
 export declare const MAX_SECRET_NAME_LENGTH = 64;
-/** Secret names the platform injects; user writes are rejected. */
+/** Secret names the platform manages; user writes are rejected. */
 export declare const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
 /**
  * Additional platform-managed env names for Cursor-hosted durable storage

package/dist/internal/hosting.js

@@ -14,7 +14,7 @@ export const MAX_SECRETS = 32;
 export const MAX_SECRET_VALUE_BYTES = 4096;
 /** Max secret name length. */
 export const MAX_SECRET_NAME_LENGTH = 64;
-/** Secret names the platform injects; user writes are rejected. */
+/** Secret names the platform manages; user writes are rejected. */
 export const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
 /**
  * Additional platform-managed env names for Cursor-hosted durable storage
@@ -73,7 +73,7 @@ export function validateSettableSecretName(name) {
         return nameError;
     }
     if (isReservedSecretName(name)) {
-        return `Secret name ${JSON.stringify(name)} is platform-managed; the platform injects CURSOR_* and Cursor-hosted storage values automatically.`;
+        return `Secret name ${JSON.stringify(name)} is platform-managed; user secrets cannot claim CURSOR_* or reserved hosted-storage names.`;
     }
     return undefined;
 }

package/dist/internal/init-project.d.ts

@@ -52,6 +52,34 @@ export interface InstallScaffoldDependenciesResult {
  * `@cursor/july` immediately after `init`.
  */
 export declare function installScaffoldDependencies(rootDir: string, options?: InstallScaffoldDependenciesOptions): Promise<InstallScaffoldDependenciesResult>;
+export interface LinkCliOntoPathOptions {
+    stdio?: "inherit" | "pipe";
+    runner?: (args: {
+        command: string;
+        args: string[];
+        cwd: string;
+        stdio: "inherit" | "pipe";
+    }) => Promise<{
+        exitCode: number;
+        stderr: string;
+    }>;
+    /** Test seam — absolute path of the linked CLI when present. */
+    whichImpl?: (command: string) => string | undefined | Promise<string | undefined>;
+}
+export interface LinkCliOntoPathResult {
+    ok: boolean;
+    exitCode: number;
+    stderr: string;
+    /** Absolute path to the linked `agent-sdk` when it resolves on PATH. */
+    resolvedPath?: string;
+}
+/**
+ * Put `agent-sdk` on the user PATH by installing the already-downloaded
+ * project copy into the npm global prefix. `npx @cursor/july init` only
+ * runs the package; this is the install that makes bare `agent-sdk …`
+ * work afterward.
+ */
+export declare function linkCliOntoPath(rootDir: string, options?: LinkCliOntoPathOptions): Promise<LinkCliOntoPathResult>;
 export interface InitScaffoldSummaryOptions {
     /** Scaffolded project root (absolute). */
     rootDir: string;
@@ -70,6 +98,11 @@ export interface InitNextStepsOptions {
      * `login` (used for `--json` and when an interactive login attempt failed).
      */
     signedIn: boolean;
+    /**
+     * True when `agent-sdk` resolves on PATH after init linked the CLI.
+     * When false, next steps include a PATH export for `node_modules/.bin`.
+     */
+    cliOnPath: boolean;
     /** Override TTY color detection (tests / `--json` callers). */
     color?: boolean;
 }
@@ -101,6 +134,7 @@ export declare function initNextCommands(options: {
     rootDir: string;
     cwd: string;
     signedIn: boolean;
+    cliOnPath: boolean;
 }): string[];
 /**
  * Coding-agent setup guide printed by `agent-serve init`

package/dist/internal/init-project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-project.d.ts","sourceRoot":"","sources":["../../src/internal/init-project.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init-project.d.ts","sourceRoot":"","sources":["../../src/internal/init-project.ts"],"names":[],"mappings":"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"}