@cursor/july 0.1.99 → 0.1.101

package/dist/extensions/cursor-cloud-agents/lib/fleet.js

@@ -0,0 +1,85 @@
+/**
+ * Who launched which cloud agent. The tools authenticate with the serve
+ * host's one Cursor API key, so the host itself must keep every session's
+ * cloud agents bound to the principal that launched them: status and
+ * follow-ups only reach agents recorded here for the same principal, and
+ * the fleet listing is that principal's records, by default narrowed to the
+ * session that launched them.
+ */
+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 { z } from "zod";
+const PREFIX = "cloud-agents";
+const fleetSchema = z.array(z.object({
+    agentId: z.string(),
+    name: z.string().optional(),
+    launchedAt: z.string(),
+    sessionId: z.string().optional(),
+}));
+const ownerSchema = z.object({ principal: z.string() });
+// `host.kv` has no compare-and-swap, and a model that launches two agents in
+// one turn calls this tool in parallel. Chain the index read-modify-write per
+// principal so neither launch overwrites the other's entry.
+const indexWrites = new Map();
+function withIndexLock(key, task) {
+    var _a;
+    const run = ((_a = indexWrites.get(key)) !== null && _a !== void 0 ? _a : Promise.resolve()).then(task, task);
+    indexWrites.set(key, run);
+    return run.finally(() => {
+        if (indexWrites.get(key) === run) {
+            indexWrites.delete(key);
+        }
+    });
+}
+/** Unauthenticated sessions (local dev, direct calls) share one principal. */
+export function principalOf(ctx) {
+    const auth = ctx.session.auth;
+    return auth === null
+        ? "anonymous"
+        : `${auth.principalType}:${auth.principalId}`;
+}
+export function recordLaunch(ctx, agentId, name) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const principal = principalOf(ctx);
+        const entry = {
+            agentId,
+            name,
+            launchedAt: new Date().toISOString(),
+            sessionId: ctx.session.id,
+        };
+        yield ctx.host.kv.put(`${PREFIX}/agents/${agentId}`, { principal });
+        yield withIndexLock(fleetKey(principal), () => __awaiter(this, void 0, void 0, function* () {
+            const fleet = yield listFleet(ctx);
+            yield ctx.host.kv.put(fleetKey(principal), [entry, ...fleet]);
+        }));
+    });
+}
+/** Refuse agents launched by another principal, or not through the extension. */
+export function assertOwned(ctx, agentId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const owner = ownerSchema.safeParse(yield ctx.host.kv.get(`${PREFIX}/agents/${agentId}`));
+        if (!owner.success || owner.data.principal !== principalOf(ctx)) {
+            throw new Error(`Agent ${agentId} was not launched through this extension by this principal; only your own launches can be read or steered.`);
+        }
+    });
+}
+/** The caller's launches, newest first: this session's, or every session's. */
+export function listFleet(ctx_1) {
+    return __awaiter(this, arguments, void 0, function* (ctx, scope = "all") {
+        const fleet = fleetSchema.safeParse(yield ctx.host.kv.get(fleetKey(principalOf(ctx))));
+        const entries = fleet.success ? fleet.data : [];
+        return scope === "all"
+            ? entries
+            : entries.filter((entry) => entry.sessionId === ctx.session.id);
+    });
+}
+function fleetKey(principal) {
+    return `${PREFIX}/principals/${encodeURIComponent(principal)}`;
+}

package/dist/extensions/cursor-cloud-agents/lib/repos.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Which repositories a launch may target. The model picks `repo` / `ref` /
+ * `prUrl` per call, but the author's `cloud.repos` are the allowlist.
+ * Model-chosen targets always require that allowlist: an unbound mount
+ * (no `cloud.repos`) must not accept an arbitrary URL under the host API
+ * key, with or without `envVars`.
+ */
+import type { AgentCloudOptions } from "../../../types.js";
+export interface LaunchTarget {
+    repo?: string;
+    ref?: string;
+    prUrl?: string;
+}
+export declare function launchRepos(target: LaunchTarget, cloud: AgentCloudOptions): AgentCloudOptions["repos"];
+//# sourceMappingURL=repos.d.ts.map

package/dist/extensions/cursor-cloud-agents/lib/repos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repos.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/lib/repos.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,iBAAiB,GACvB,iBAAiB,CAAC,OAAO,CAAC,CAsD5B"}

package/dist/extensions/cursor-cloud-agents/lib/repos.js

@@ -0,0 +1,55 @@
+/**
+ * Which repositories a launch may target. The model picks `repo` / `ref` /
+ * `prUrl` per call, but the author's `cloud.repos` are the allowlist.
+ * Model-chosen targets always require that allowlist: an unbound mount
+ * (no `cloud.repos`) must not accept an arbitrary URL under the host API
+ * key, with or without `envVars`.
+ */
+import { parsePrUrl } from "../../../internal/scm/pr-url.js";
+export function launchRepos(target, cloud) {
+    var _a, _b;
+    var _c, _d, _e, _f, _g;
+    if (target.repo === undefined &&
+        target.ref === undefined &&
+        target.prUrl === undefined) {
+        return cloud.repos;
+    }
+    const pr = target.prUrl === undefined ? undefined : parsePrUrl(target.prUrl);
+    if (target.prUrl !== undefined && (pr === null || pr === void 0 ? void 0 : pr.provider) !== "github") {
+        throw new Error(`prUrl must be a GitHub pull request URL: ${target.prUrl}`);
+    }
+    const prRepo = pr === undefined ? undefined : `https://github.com/${pr.owner}/${pr.repo}`;
+    // A lone `ref` needs exactly one configured repository to apply to.
+    const configured = (_c = cloud.repos) !== null && _c !== void 0 ? _c : [];
+    const url = (_e = (_d = target.repo) !== null && _d !== void 0 ? _d : prRepo) !== null && _e !== void 0 ? _e : (configured.length === 1 ? (_a = configured[0]) === null || _a === void 0 ? void 0 : _a.url : undefined);
+    if (url === undefined) {
+        throw new Error(configured.length > 1
+            ? "`repo` is required: this extension configures several repositories."
+            : "`repo` is required: this extension has no configured default repository.");
+    }
+    if (prRepo !== undefined && repoKey(prRepo) !== repoKey(url)) {
+        throw new Error(`prUrl ${target.prUrl} is not a pull request of ${url}.`);
+    }
+    const allowlisted = (_b = cloud.repos) === null || _b === void 0 ? void 0 : _b.some((configured) => repoKey(configured.url) === repoKey(url));
+    if (allowlisted !== true) {
+        throw new Error(cloud.repos === undefined
+            ? `Configure cloud.repos before launching against a model-chosen repository (${url}).`
+            : `${url} is not one of this extension's configured repositories.`);
+    }
+    // Keep the matching allowlist entry's branch / PR defaults when the model
+    // only names the repository (handoff always passes `repo`). An explicit
+    // `ref` clears an inherited `prUrl` so branch and PR targets do not mix.
+    const match = configured.find((configuredRepo) => repoKey(configuredRepo.url) === repoKey(url));
+    return [
+        {
+            url,
+            startingRef: (_f = target.ref) !== null && _f !== void 0 ? _f : match === null || match === void 0 ? void 0 : match.startingRef,
+            prUrl: (_g = target.prUrl) !== null && _g !== void 0 ? _g : (target.ref !== undefined ? undefined : match === null || match === void 0 ? void 0 : match.prUrl),
+        },
+    ];
+}
+function repoKey(url) {
+    const parsed = new URL(url);
+    const path = parsed.pathname.replace(/\.git$/, "").replace(/\/+$/, "");
+    return `${parsed.hostname}${path}`.toLowerCase();
+}

package/dist/extensions/cursor-cloud-agents/skills/handoff.md

@@ -0,0 +1,27 @@
+---
+description: "Delegate coding work to Cursor cloud agents: when to hand off, how to write the prompt, and how to follow up and check status."
+---
+
+# Cloud agent handoff
+
+Hand work to a Cursor cloud agent when it needs a repository checkout, a long run, or an isolated machine: implementing a change, running a test suite, opening a pull request. Answer questions and small reads yourself.
+
+The tools below are this extension's; they appear under its mount namespace, as `<namespace>__launch` and so on.
+
+## Launch
+
+Call `launch` with a self-contained prompt: the goal, the repository or pull request, constraints (branch, files to leave alone), and what done looks like (tests pass, PR opened). Pass `ref` or `prUrl` to pick a branch or pull request; `repo` must be one of the configured repositories.
+
+The result carries `agentId` (`bc-...`) and a `url`. Report both in full. Never truncate the id.
+
+## Follow up
+
+Call `follow_up` with the `agentId` to steer an agent you launched or ask for changes on its branch. A busy agent rejects the follow-up: check status and retry once its run has finished. Do not launch a second agent for follow-up work on the same branch.
+
+## Check status
+
+Call `status` with the `agentId`. The latest run carries `status` (`running`, `finished`, `error`, or `cancelled`), the final `result` text, an `error` message, and any pushed `branches` or pull requests; the agent itself reports `archived`. A run takes minutes: check when asked or when you need the result, not in a tight loop.
+
+## Fleet
+
+`list` returns the agents launched in this session, newest first; pass `scope: "all"` to include your launches from other sessions. Launch one agent per independent task and give each a descriptive `name`. Agents launched by others are out of reach.

package/dist/extensions/cursor-cloud-agents/tools/follow_up.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../../../types.js";
+declare const follow_up: ToolDefinition;
+export default follow_up;
+//# sourceMappingURL=follow_up.d.ts.map

package/dist/extensions/cursor-cloud-agents/tools/follow_up.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow_up.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/tools/follow_up.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKxD,QAAA,MAAM,SAAS,EAAE,cAkBf,CAAC;eAEY,SAAS"}

package/dist/extensions/cursor-cloud-agents/tools/follow_up.js

@@ -0,0 +1,37 @@
+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 { Agent } from "@cursor/sdk";
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import extension from "../extension.js";
+import { agentRef, apiKey } from "../lib/cloud.js";
+import { assertOwned } from "../lib/fleet.js";
+const follow_up = defineTool({
+    description: "Send a follow-up prompt to a cloud agent you launched. The agent must be idle; a busy agent rejects the follow-up.",
+    effect: "write",
+    needsApproval: () => extension.config.needsApproval,
+    inputSchema: agentRef.extend({
+        prompt: z.string().min(1).describe("The follow-up instruction."),
+    }),
+    execute(input, ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield assertOwned(ctx, input.agentId);
+            const agent = yield Agent.resume(input.agentId, { apiKey: apiKey() });
+            try {
+                const run = yield agent.send(input.prompt);
+                return { agentId: input.agentId, runId: run.id, status: run.status };
+            }
+            finally {
+                agent.close();
+            }
+        });
+    },
+});
+export default follow_up;

package/dist/extensions/cursor-cloud-agents/tools/launch.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../../../types.js";
+declare const launch: ToolDefinition;
+export default launch;
+//# sourceMappingURL=launch.d.ts.map

package/dist/extensions/cursor-cloud-agents/tools/launch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/tools/launch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD,QAAA,MAAM,MAAM,EAAE,cAwEZ,CAAC;eAEY,MAAM"}

package/dist/extensions/cursor-cloud-agents/tools/launch.js

@@ -0,0 +1,83 @@
+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 { Agent } from "@cursor/sdk";
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import extension from "../extension.js";
+import { agentUrl, agentView, apiKey, modelSelection } from "../lib/cloud.js";
+import { recordLaunch } from "../lib/fleet.js";
+import { launchRepos } from "../lib/repos.js";
+const launch = defineTool({
+    description: "Launch a Cursor cloud agent on a repository with a self-contained task. Returns the agent id and URL; check progress with the status tool.",
+    effect: "write",
+    needsApproval: () => extension.config.needsApproval,
+    inputSchema: z.object({
+        prompt: z
+            .string()
+            .min(1)
+            .describe("Self-contained task: goal, constraints, and what done looks like."),
+        repo: z
+            .string()
+            .url()
+            .optional()
+            .describe("GitHub repository URL, one of the configured repositories. Defaults to the configured repository."),
+        ref: z.string().optional().describe("Starting branch or commit."),
+        prUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Work on this pull request's branch instead of a new one."),
+        name: z
+            .string()
+            .max(100)
+            .optional()
+            .describe("Display name; derived from the prompt when omitted."),
+    }),
+    execute(input, ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { cloud } = extension.config;
+            const key = apiKey();
+            const agent = yield Agent.create({
+                apiKey: key,
+                model: modelSelection(),
+                name: input.name,
+                cloud: Object.assign(Object.assign({}, cloud), { repos: launchRepos(input, cloud) }),
+            });
+            try {
+                const run = yield agent.send(input.prompt);
+                yield recordLaunch(ctx, agent.agentId, input.name);
+                return {
+                    agentId: agent.agentId,
+                    runId: run.id,
+                    status: run.status,
+                    url: agentUrl(agent.agentId),
+                };
+            }
+            catch (error) {
+                // The API can fail after the agent exists (slow admission,
+                // post-create checks). The SDK seeded the id unless envVars made
+                // the server mint it, so read the agent back and keep the handle;
+                // envVars launches have no id to read back and surface the error.
+                const info = cloud.envVars === undefined
+                    ? yield Agent.get(agent.agentId, { apiKey: key }).catch(() => undefined)
+                    : undefined;
+                if (info === undefined) {
+                    throw error;
+                }
+                yield recordLaunch(ctx, info.agentId, input.name);
+                return Object.assign(Object.assign({}, agentView(info)), { launchError: error instanceof Error ? error.message : String(error) });
+            }
+            finally {
+                agent.close();
+            }
+        });
+    },
+});
+export default launch;

package/dist/extensions/cursor-cloud-agents/tools/list.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../../../types.js";
+declare const list: ToolDefinition;
+export default list;
+//# sourceMappingURL=list.d.ts.map

package/dist/extensions/cursor-cloud-agents/tools/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/tools/list.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,QAAA,MAAM,IAAI,EAAE,cAsBV,CAAC;eAEY,IAAI"}

package/dist/extensions/cursor-cloud-agents/tools/list.js

@@ -0,0 +1,36 @@
+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 { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import { agentUrl } from "../lib/cloud.js";
+import { listFleet } from "../lib/fleet.js";
+const list = defineTool({
+    description: 'List the cloud agents launched in this session, newest first. Pass scope "all" for every agent you launched, in any session.',
+    effect: "read",
+    inputSchema: z.object({
+        scope: z
+            .enum(["session", "all"])
+            .default("session")
+            .describe("session: agents this session launched; all: every agent launched by you, in any session."),
+        limit: z.number().int().min(1).max(100).default(20),
+    }),
+    execute(input, ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fleet = yield listFleet(ctx, input.scope);
+            return {
+                sessionId: ctx.session.id,
+                agents: fleet
+                    .slice(0, input.limit)
+                    .map((entry) => (Object.assign(Object.assign({}, entry), { url: agentUrl(entry.agentId) }))),
+            };
+        });
+    },
+});
+export default list;

package/dist/extensions/cursor-cloud-agents/tools/status.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../../../types.js";
+declare const status: ToolDefinition;
+export default status;
+//# sourceMappingURL=status.d.ts.map

package/dist/extensions/cursor-cloud-agents/tools/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/tools/status.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,QAAA,MAAM,MAAM,EAAE,cA6BZ,CAAC;eAEY,MAAM"}

package/dist/extensions/cursor-cloud-agents/tools/status.js

@@ -0,0 +1,41 @@
+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 { Agent } from "@cursor/sdk";
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import { agentRef, agentView, apiKey, runView } from "../lib/cloud.js";
+import { assertOwned } from "../lib/fleet.js";
+const status = defineTool({
+    description: "Read a cloud agent you launched and its latest run: state, final result text, error, and pushed branches or pull requests.",
+    effect: "read",
+    inputSchema: agentRef.extend({
+        runId: z
+            .string()
+            .optional()
+            .describe("A specific run; defaults to the latest."),
+    }),
+    execute(input, ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b;
+            yield assertOwned(ctx, input.agentId);
+            const key = apiKey();
+            const cloud = { runtime: "cloud", apiKey: key };
+            const info = yield Agent.get(input.agentId, { apiKey: key });
+            // The run list carries no result text; fetch the run itself.
+            const runId = (_b = input.runId) !== null && _b !== void 0 ? _b : (_a = (yield Agent.listRuns(input.agentId, Object.assign(Object.assign({}, cloud), { limit: 1 }))).items[0]) === null || _a === void 0 ? void 0 : _a.id;
+            const run = runId === undefined
+                ? undefined
+                : yield Agent.getRun(runId, Object.assign(Object.assign({}, cloud), { agentId: input.agentId }));
+            return Object.assign(Object.assign({}, agentView(info)), { run: run === undefined ? undefined : runView(run) });
+        });
+    },
+});
+export default status;

package/dist/extensions.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Extensions — agent-shaped trees an agent mounts under a namespace.
+ *
+ * An extension is a directory laid out like `agent/`: `extension.ts`
+ * declares it, `tools/<name>.ts` and `skills/<name>.md|ts` are its
+ * contributions, `lib/` holds shared code.
+ *
+ * ```ts
+ * // extension.ts
+ * import { defineExtension } from "@cursor/july/extensions";
+ * import { z } from "zod";
+ *
+ * export default defineExtension({
+ *   root: import.meta.dirname,
+ *   description: "CRM lookups.",
+ *   config: z.object({ apiKey: z.string() }),
+ * });
+ *
+ * // tools/search.ts
+ * import extension from "../extension.js";
+ *
+ * export default defineTool({
+ *   description: "Search the CRM.",
+ *   execute: (input) => search(extension.config.apiKey, input),
+ * });
+ * ```
+ *
+ * A consumer mounts it from `agent/extensions/<ns>.ts`; the filename is the
+ * namespace, and every contribution is exposed as `<ns>__<name>`
+ * (`crm__search`). `__` is reserved for that: an authored `agent/tools/` or
+ * `agent/skills/` name may not contain it.
+ *
+ * ```ts
+ * // agent/extensions/crm.ts
+ * import crm from "@acme/crm";
+ *
+ * export default crm({ apiKey: process.env.CRM_API_KEY! });
+ * ```
+ *
+ * To adjust a contribution, mount as a directory instead and overlay the
+ * slot: `agent/extensions/crm/extension.ts` holds the mount, and
+ * `agent/extensions/crm/tools/search.ts` replaces `crm__search` — or removes
+ * it with `export default disableTool()`.
+ */
+import type { DisabledToolDefinition, Extension, ExtensionOptions } from "./types.js";
+export type { DisabledToolDefinition, DiscoveredExtension, Extension, ExtensionDeclaration, ExtensionMount, ExtensionOptions, } from "./types.js";
+export declare function defineExtension<TConfig = undefined, TInput = TConfig>(options: ExtensionOptions<TConfig, TInput>): Extension<TConfig, TInput>;
+export declare function disableTool(): DisabledToolDefinition;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,KAAK,EACV,sBAAsB,EACtB,SAAS,EAET,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,sBAAsB,EACtB,mBAAmB,EACnB,SAAS,EACT,oBAAoB,EACpB,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,eAAe,CAAC,OAAO,GAAG,SAAS,EAAE,MAAM,GAAG,OAAO,EACnE,OAAO,EAAE,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,GACzC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CA6B5B;AAED,wBAAgB,WAAW,IAAI,sBAAsB,CAEpD"}

package/dist/extensions.js

@@ -0,0 +1,75 @@
+/**
+ * Extensions — agent-shaped trees an agent mounts under a namespace.
+ *
+ * An extension is a directory laid out like `agent/`: `extension.ts`
+ * declares it, `tools/<name>.ts` and `skills/<name>.md|ts` are its
+ * contributions, `lib/` holds shared code.
+ *
+ * ```ts
+ * // extension.ts
+ * import { defineExtension } from "@cursor/july/extensions";
+ * import { z } from "zod";
+ *
+ * export default defineExtension({
+ *   root: import.meta.dirname,
+ *   description: "CRM lookups.",
+ *   config: z.object({ apiKey: z.string() }),
+ * });
+ *
+ * // tools/search.ts
+ * import extension from "../extension.js";
+ *
+ * export default defineTool({
+ *   description: "Search the CRM.",
+ *   execute: (input) => search(extension.config.apiKey, input),
+ * });
+ * ```
+ *
+ * A consumer mounts it from `agent/extensions/<ns>.ts`; the filename is the
+ * namespace, and every contribution is exposed as `<ns>__<name>`
+ * (`crm__search`). `__` is reserved for that: an authored `agent/tools/` or
+ * `agent/skills/` name may not contain it.
+ *
+ * ```ts
+ * // agent/extensions/crm.ts
+ * import crm from "@acme/crm";
+ *
+ * export default crm({ apiKey: process.env.CRM_API_KEY! });
+ * ```
+ *
+ * To adjust a contribution, mount as a directory instead and overlay the
+ * slot: `agent/extensions/crm/extension.ts` holds the mount, and
+ * `agent/extensions/crm/tools/search.ts` replaces `crm__search` — or removes
+ * it with `export default disableTool()`.
+ */
+import { brandDefinition } from "./internal/brand.js";
+export function defineExtension(options) {
+    let mounted;
+    const mount = (config) => {
+        const parsed = options.config === undefined
+            ? config
+            : options.config.parse(config);
+        mounted = { config: parsed };
+        return brandDefinition("extension", {
+            extension: handle,
+            config: parsed,
+        });
+    };
+    const handle = Object.defineProperties(mount, {
+        root: { value: options.root, enumerable: true },
+        description: { value: options.description, enumerable: true },
+        config: {
+            enumerable: true,
+            get() {
+                if (mounted === undefined) {
+                    throw new Error(`Extension at ${options.root} read its config before an agent mounted it. Mount it from agent/extensions/<ns>.ts; the mount runs before the tree loads.`);
+                }
+                return mounted.config;
+            },
+        },
+    });
+    return handle;
+}
+export function disableTool() {
+    return brandDefinition("disabled-tool", {});
+}

package/dist/files-backends/cursor-hosted.d.ts

@@ -101,6 +101,12 @@ export interface CursorHostedFilesOptions {
     resolveApiKey?: () => string | undefined;
     /** File store to address (default: `AGENT_SERVE_STORE_SOURCE_ID`). */
     storeSourceId?: string;
+    /**
+     * Lazy store source id, re-resolved on every call and preferred over
+     * {@link storeSourceId} — freeze bind drops ids into `/run/cursor/secrets`
+     * after serve start without restarting July.
+     */
+    resolveStoreSourceId?: () => string | undefined;
     /** Test seam; defaults to global fetch. */
     fetch?: typeof fetch;
 }

package/dist/files-backends/cursor-hosted.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-hosted.d.ts","sourceRoot":"","sources":["../../src/files-backends/cursor-hosted.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,YAAY,EAGlB,MAAM,aAAa,CAAC;AAWrB;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,gCACjB,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6CAA6C,0CACjB,CAAC;AAgB1C;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAGT;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAGpB;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAYT;AAED,MAAM,WAAW,wBAAwB;IACvC,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACzC,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAuCD,KAAK,kBAAkB,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG;IAChD,gFAAgF;IAChF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,kBAAkB,CAwXpB"}
+{"version":3,"file":"cursor-hosted.d.ts","sourceRoot":"","sources":["../../src/files-backends/cursor-hosted.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,YAAY,EAGlB,MAAM,aAAa,CAAC;AAerB;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,gCACjB,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6CAA6C,0CACjB,CAAC;AAgB1C;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAEpB;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAYT;AAED,MAAM,WAAW,wBAAwB;IACvC,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACzC,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAChD,2CAA2C;IAC3C,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAuCD,KAAK,kBAAkB,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG;IAChD,gFAAgF;IAChF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,kBAAkB,CAwXpB"}

package/dist/files-backends/cursor-hosted.js

@@ -53,6 +53,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { createHash } from "node:crypto";
 import { FileConflictError, } from "../files.js";
+import { resolveDeploymentStoreSourceIdSync, resolveFrameworkStoreSourceIdSync, } from "../internal/cursor/hosted-store-secrets.js";
 import { createAgentStorePresignedUrlValidatorForBackend } from "./agent-store-presigned-url.js";
 /**
  * Same default as the hosted storage backend, inlined so this entrypoint does
@@ -102,9 +103,7 @@ const MAX_LIST_WALK_PAGES = 1000;
  * loudly when the sink is used.
  */
 export function isCursorHostedFilesAvailable(env = process.env) {
-    var _a;
-    const sourceId = (_a = env[AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR]) === null || _a === void 0 ? void 0 : _a.trim();
-    return sourceId !== undefined && sourceId !== "";
+    return resolveDeploymentStoreSourceIdSync(env) !== undefined;
 }
 /**
  * The framework-level store's source id, or `undefined` when the deployment
@@ -114,9 +113,7 @@ export function isCursorHostedFilesAvailable(env = process.env) {
  * credential must fail loudly at use, not silently deselect the store.
  */
 export function cursorFrameworkStoreSourceId(env = process.env) {
-    var _a;
-    const sourceId = (_a = env[AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_ENV_VAR]) === null || _a === void 0 ? void 0 : _a.trim();
-    return sourceId === undefined || sourceId === "" ? undefined : sourceId;
+    return resolveFrameworkStoreSourceIdSync(env);
 }
 /**
  * Local `serve`/`run` with a personal `CURSOR_API_KEY` can address
@@ -523,9 +520,9 @@ function fetchImpl(options) {
  * address, and writing somewhere else silently is worse than not writing.
  */
 function resolveStoreSourceId(options) {
-    var _a;
-    var _b;
-    const id = (_a = ((_b = options.storeSourceId) !== null && _b !== void 0 ? _b : process.env[AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR])) === null || _a === void 0 ? void 0 : _a.trim();
+    var _a, _b;
+    var _c, _d;
+    const id = (_b = ((_d = (_c = (_a = options.resolveStoreSourceId) === null || _a === void 0 ? void 0 : _a.call(options)) !== null && _c !== void 0 ? _c : options.storeSourceId) !== null && _d !== void 0 ? _d : resolveDeploymentStoreSourceIdSync(process.env))) === null || _b === void 0 ? void 0 : _b.trim();
     if (id === undefined || id === "") {
         throw new Error(`cursorHostedFiles requires ${AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR} (set on Cursor-managed deployments)`);
     }

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { allowAll, bearerAuth, DELETE, defineChannel, GET, httpChannel, localDev
 export { defineConnection } from "./connections.js";
 export type { ContinuationBuiltin, ContinuationClaim, ContinuationIdentity, ContinuationSelector, ConversationType, MailboxContinuation, ParsedContinuation, } from "./continuation.js";
 export { BUILTINS, bindMailboxContinuationSend, CONTINUATION_SELECTORS, continuationSource, defaultContinuationSelector, extractContinuation, formatConversationKey, handshakeContinuation, isContinuationSelector, mintClaim, normalizeIdentity, parseContinuationSelector, resolveContinuation, resolveV2Key, stampMailboxContinuation, V2EngineError, } from "./continuation.js";
+export { defineExtension, disableTool } from "./extensions.js";
 export { defineHook } from "./hooks.js";
 export { InvalidAsOfError, VacuousTimeArgsError, } from "./internal/as-of.js";
 export type { LoadAgentProjectOptions } from "./internal/discovery.js";
@@ -44,7 +45,7 @@ export type { DurableSessionRecord, DurableSessionSummary, StorageABTable, Stora
 export { defineStorage, isDurableSessionRecordKey, parseDurableSessionRecord, STORAGE_KEY_ROOT, storageKeys, summarizeDurableSessionRecord, } from "./storage.js";
 export { defineTool } from "./tools.js";
 export type * from "./types.js";
-export { cursorAccountServersHasMixedWildcard, DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, isCursorAccountTransport, isPeerConnectionTransport, isSymbolicConnectionTransport, isToolEffect, MAX_RUNNING_TURNS_LIMIT, normalizeConnectionEffects, normalizeCursorAccountServers, supportsKvCas, } from "./types.js";
+export { cursorAccountServersHasMixedWildcard, DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, isCursorAccountTransport, isPeerConnectionTransport, isSymbolicConnectionTransport, isToolEffect, MAX_RUNNING_TURNS_LIMIT, normalizeConnectionEffects, normalizeConnectionTools, normalizeCursorAccountServers, supportsKvCas, } from "./types.js";
 /**
  * Runtime config for an agent — authored at `agent/agent.ts` (the root
  * agent) or `agent/subagents/<id>/agent.ts` (a subagent). Set