@cursor/july 0.1.100 → 0.1.101

package/src/extensions/cursor-cloud-agents/lib/repos.ts

@@ -0,0 +1,81 @@
+/**
+ * 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";
+import type { AgentCloudOptions } from "../../../types.js";
+
+export interface LaunchTarget {
+  repo?: string;
+  ref?: string;
+  prUrl?: string;
+}
+
+export function launchRepos(
+  target: LaunchTarget,
+  cloud: AgentCloudOptions
+): AgentCloudOptions["repos"] {
+  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?.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 = cloud.repos ?? [];
+  const url =
+    target.repo ??
+    prRepo ??
+    (configured.length === 1 ? configured[0]?.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 = cloud.repos?.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: target.ref ?? match?.startingRef,
+      prUrl:
+        target.prUrl ?? (target.ref !== undefined ? undefined : match?.prUrl),
+    },
+  ];
+}
+
+function repoKey(url: string): string {
+  const parsed = new URL(url);
+  const path = parsed.pathname.replace(/\.git$/, "").replace(/\/+$/, "");
+  return `${parsed.hostname}${path}`.toLowerCase();
+}

package/src/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/src/extensions/cursor-cloud-agents/tools/follow_up.ts

@@ -0,0 +1,29 @@
+import { Agent } from "@cursor/sdk";
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import extension from "../extension.js";
+import { agentRef, apiKey } from "../lib/cloud.js";
+import { assertOwned } from "../lib/fleet.js";
+
+const follow_up: ToolDefinition = 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."),
+  }),
+  async execute(input, ctx) {
+    await assertOwned(ctx, input.agentId);
+    const agent = await Agent.resume(input.agentId, { apiKey: apiKey() });
+    try {
+      const run = await agent.send(input.prompt);
+      return { agentId: input.agentId, runId: run.id, status: run.status };
+    } finally {
+      agent.close();
+    }
+  },
+});
+
+export default follow_up;

package/src/extensions/cursor-cloud-agents/tools/launch.ts

@@ -0,0 +1,84 @@
+import { Agent } from "@cursor/sdk";
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.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: ToolDefinition = 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."),
+  }),
+  async execute(input, ctx) {
+    const { cloud } = extension.config;
+    const key = apiKey();
+    const agent = await Agent.create({
+      apiKey: key,
+      model: modelSelection(),
+      name: input.name,
+      cloud: { ...cloud, repos: launchRepos(input, cloud) },
+    });
+    try {
+      const run = await agent.send(input.prompt);
+      await 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
+          ? await Agent.get(agent.agentId, { apiKey: key }).catch(
+              () => undefined
+            )
+          : undefined;
+      if (info === undefined) {
+        throw error;
+      }
+      await recordLaunch(ctx, info.agentId, input.name);
+      return {
+        ...agentView(info),
+        launchError: error instanceof Error ? error.message : String(error),
+      };
+    } finally {
+      agent.close();
+    }
+  },
+});
+
+export default launch;

package/src/extensions/cursor-cloud-agents/tools/list.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import { agentUrl } from "../lib/cloud.js";
+import { listFleet } from "../lib/fleet.js";
+
+const list: ToolDefinition = 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),
+  }),
+  async execute(input, ctx) {
+    const fleet = await listFleet(ctx, input.scope);
+    return {
+      sessionId: ctx.session.id,
+      agents: fleet
+        .slice(0, input.limit)
+        .map((entry) => ({ ...entry, url: agentUrl(entry.agentId) })),
+    };
+  },
+});
+
+export default list;

package/src/extensions/cursor-cloud-agents/tools/status.ts

@@ -0,0 +1,39 @@
+import { Agent } from "@cursor/sdk";
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import { agentRef, agentView, apiKey, runView } from "../lib/cloud.js";
+import { assertOwned } from "../lib/fleet.js";
+
+const status: ToolDefinition = 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."),
+  }),
+  async execute(input, ctx) {
+    await assertOwned(ctx, input.agentId);
+    const key = apiKey();
+    const cloud = { runtime: "cloud", apiKey: key } as const;
+    const info = await Agent.get(input.agentId, { apiKey: key });
+    // The run list carries no result text; fetch the run itself.
+    const runId =
+      input.runId ??
+      (await Agent.listRuns(input.agentId, { ...cloud, limit: 1 })).items[0]
+        ?.id;
+    const run =
+      runId === undefined
+        ? undefined
+        : await Agent.getRun(runId, { ...cloud, agentId: input.agentId });
+    return {
+      ...agentView(info),
+      run: run === undefined ? undefined : runView(run),
+    };
+  },
+});
+
+export default status;

package/src/extensions.ts

@@ -0,0 +1,98 @@
+/**
+ * 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";
+import type {
+  DisabledToolDefinition,
+  Extension,
+  ExtensionMount,
+  ExtensionOptions,
+} from "./types.js";
+
+export type {
+  DisabledToolDefinition,
+  DiscoveredExtension,
+  Extension,
+  ExtensionDeclaration,
+  ExtensionMount,
+  ExtensionOptions,
+} from "./types.js";
+
+export function defineExtension<TConfig = undefined, TInput = TConfig>(
+  options: ExtensionOptions<TConfig, TInput>
+): Extension<TConfig, TInput> {
+  let mounted: { config: TConfig } | undefined;
+  const mount = (config?: TInput): ExtensionMount => {
+    const parsed =
+      options.config === undefined
+        ? (config as unknown as TConfig)
+        : 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(): TConfig {
+        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;
+      },
+    },
+  }) as unknown as Extension<TConfig, TInput>;
+  return handle;
+}
+
+export function disableTool(): DisabledToolDefinition {
+  return brandDefinition("disabled-tool", {});
+}

package/src/index.ts

@@ -78,6 +78,7 @@ export {
   stampMailboxContinuation,
   V2EngineError,
 } from "./continuation.js";
+export { defineExtension, disableTool } from "./extensions.js";
 export { defineHook } from "./hooks.js";
 export {
   InvalidAsOfError,
@@ -189,6 +190,7 @@ export {
   isToolEffect,
   MAX_RUNNING_TURNS_LIMIT,
   normalizeConnectionEffects,
+  normalizeConnectionTools,
   normalizeCursorAccountServers,
   supportsKvCas,
 } from "./types.js";

package/src/internal/advertise-tools.ts

@@ -27,21 +27,25 @@
  * `defineConnection({ effects })` filters the listing before names are
  * assigned: only tools whose MCP annotations classify as an intended
  * effect are advertised. Unclassified tools are omitted, not guessed.
+ * `defineConnection({ tools: [...] })` keeps only the named tools.
+ * `disallowedTools` drops names. A name filter that matches nothing on
+ * the server fails the turn.
  * Tools whose `annotations.title` is `do-not-call` are dropped as well
  * (vendor host-UI / MCP Apps helpers that still carry `readOnlyHint`).
  */
 
-import type {
-  DiscoveredConnection,
-  DiscoveredTool,
-  HostMcpCallResult,
-  HostMcpToolInfo,
-  JsonSchemaObject,
-  McpToolAnnotations,
-  ResolvedAgent,
-  SessionInfo,
-  ToolDefinition,
-  ToolEffect,
+import {
+  connectionAllowsTool,
+  type DiscoveredConnection,
+  type DiscoveredTool,
+  type HostMcpCallResult,
+  type HostMcpToolInfo,
+  type JsonSchemaObject,
+  type McpToolAnnotations,
+  type ResolvedAgent,
+  type SessionInfo,
+  type ToolDefinition,
+  type ToolEffect,
 } from "../types.js";
 import { brandDefinition } from "./brand.js";
 import type { HostMcpOneOff } from "./mcp-host.js";
@@ -136,7 +140,14 @@ export async function resolveAdvertisedTools(args: {
       try {
         const source = await sourceFor(connection, args.session, args.hostMcp);
         const listed = await source.listTools();
-        return { connection, ok: true, source, listed };
+        return {
+          connection,
+          ok: true,
+          source,
+          listed: listed.filter((info) =>
+            connectionAllowsTool(connection, info.name)
+          ),
+        };
       } catch (error) {
         return { connection, ok: false, error };
       }
@@ -157,6 +168,20 @@ export async function resolveAdvertisedTools(args: {
       );
     }
     const { source, listed } = listing;
+    if (
+      (connection.tools !== undefined ||
+        connection.disallowedTools !== undefined) &&
+      listed.length === 0
+    ) {
+      const error = new Error(
+        `Advertised connection "${connection.name}" tool filter matched no tools on the server.`
+      );
+      if (args.onConnectionError !== undefined) {
+        args.onConnectionError(connection.name, error);
+        continue;
+      }
+      throw error;
+    }
     const intended = listed.filter(
       (info) =>
         !isDoNotCallTool(info.annotations) &&

package/src/internal/as-of.ts

@@ -105,3 +105,166 @@ export function timeArgViolation(
   }
   return undefined;
 }
+
+// Whole-string only: a query that merely contains "now" is not a bound.
+// Duration-only strings (`30m`, `2h`) and last/this plus a non-window word
+// (`last modified`) are not time bounds. Calendar-aligned `now/d` is.
+const TIME_UNIT =
+  "(?:s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days|w|week|weeks|mo|month|months|y|yr|yrs|year|years)";
+const WINDOW_WORD =
+  "(?:second|seconds|minute|minutes|hour|hours|day|days|week|weeks|month|months|year|years|quarter|quarters|weekend|monday|tuesday|wednesday|thursday|friday|saturday|sunday|morning|afternoon|evening|night)";
+const RELATIVE_TIME_EXPRESSION = new RegExp(
+  `^(?:now(?:\\s*[+-]\\s*\\d+\\s*${TIME_UNIT}\\b.*|/[a-zA-Z]+.*)?|[+-]\\d+\\s*${TIME_UNIT}|today|yesterday|tomorrow|(?:last|this)\\s+${WINDOW_WORD})$`,
+  "i"
+);
+
+function forwardTimeReason(
+  value: unknown,
+  asOf: string,
+  frozenMs: number
+): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    return undefined;
+  }
+  if (RELATIVE_TIME_EXPRESSION.test(trimmed)) {
+    return (
+      `Argument ${JSON.stringify(value)} is a relative time expression, ` +
+      `which reads against the real present. This session reads the world ` +
+      `as of ${asOf}; supply an absolute ISO-8601 instant with a timezone ` +
+      `at or before that instant and retry.`
+    );
+  }
+  const instant = parseInstant(trimmed);
+  if (instant !== undefined && instant.getTime() > frozenMs) {
+    return (
+      `Argument ${JSON.stringify(value)} is later than the instant this ` +
+      `session reads the world as of (${asOf}). Supply a bound at or before ` +
+      `that instant and retry.`
+    );
+  }
+  return undefined;
+}
+
+/** Relative expressions or instants after `asOf`. Numeric epochs need `timeArgs`. */
+export function forwardTimeArgument(
+  input: unknown,
+  asOf: string
+): string | undefined {
+  const frozenMs = new Date(asOf).getTime();
+  const seen = new Set<unknown>();
+  const walk = (value: unknown, depth: number): string | undefined => {
+    if (depth > 8) {
+      return undefined;
+    }
+    const reason = forwardTimeReason(value, asOf, frozenMs);
+    if (reason !== undefined) {
+      return reason;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        const found = walk(item, depth + 1);
+        if (found !== undefined) {
+          return found;
+        }
+      }
+      return undefined;
+    }
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) {
+        return undefined;
+      }
+      seen.add(value);
+      for (const item of Object.values(value as Record<string, unknown>)) {
+        const found = walk(item, depth + 1);
+        if (found !== undefined) {
+          return found;
+        }
+      }
+    }
+    return undefined;
+  };
+  return walk(input, 0);
+}
+
+/**
+ * Property names that carry a query's time window when a vendor schema
+ * declares them. Deliberately narrower than the embedded-filter key list:
+ * these must be safe to *require*, so only unambiguous window names — never
+ * `timestamp`/`date`, which name data fields more often than bounds.
+ */
+const TIME_WINDOW_KEYS = new Set([
+  "from",
+  "to",
+  "since",
+  "until",
+  "start",
+  "end",
+  "start_time",
+  "end_time",
+  "starttime",
+  "endtime",
+]);
+
+/**
+ * The string-typed time-window properties a tool's input schema declares.
+ * String-typed only: a numeric `from` is a pagination offset more often than
+ * an instant, and requiring an ISO value there would break the call.
+ */
+export function schemaTimeWindowKeys(
+  inputSchema: { properties?: Record<string, unknown> } | undefined
+): string[] {
+  const properties = inputSchema?.properties;
+  if (properties === undefined) {
+    return [];
+  }
+  const keys: string[] = [];
+  for (const [name, spec] of Object.entries(properties)) {
+    if (!TIME_WINDOW_KEYS.has(name.toLowerCase())) {
+      continue;
+    }
+    const type =
+      typeof spec === "object" && spec !== null
+        ? (spec as { type?: unknown }).type
+        : undefined;
+    const types = Array.isArray(type) ? type : [type];
+    if (types.includes("string")) {
+      keys.push(name);
+    }
+  }
+  return keys;
+}
+
+/**
+ * An omitted time window on a vendor tool is not "no window" — the vendor
+ * fills it with a live default (Datadog: `now-1h`..`now`), which the walker
+ * cannot see because the value is never present. In a frozen session a call
+ * that omits a schema-declared window key is refused so the model supplies
+ * the bound explicitly, where {@link forwardTimeArgument} then checks it.
+ */
+export function missingTimeWindow(
+  input: unknown,
+  windowKeys: readonly string[],
+  asOf: string
+): string | undefined {
+  if (windowKeys.length === 0) {
+    return undefined;
+  }
+  const record =
+    typeof input === "object" && input !== null
+      ? (input as Record<string, unknown>)
+      : {};
+  const missing = windowKeys.filter((key) => record[key] === undefined);
+  if (missing.length === 0) {
+    return undefined;
+  }
+  return (
+    `This tool fills omitted time bounds (${missing.join(", ")}) with a ` +
+    `live default window, which reads the real present. This session reads ` +
+    `the world as of ${asOf}; supply each bound explicitly as an absolute ` +
+    `ISO-8601 instant with a timezone at or before that instant and retry.`
+  );
+}