@cursor/july 0.1.99 → 0.1.101

package/src/types.ts

@@ -50,6 +50,8 @@ export type DefinitionKind =
   | "instructions"
   | "tool"
   | "skill"
+  | "extension"
+  | "disabled-tool"
   | "connection"
   | "channel"
   | "http-channel"
@@ -952,6 +954,42 @@ export function normalizeConnectionEffects(
   return unique;
 }
 
+/**
+ * Trim, drop blanks, and unique-preserve authored
+ * {@link ConnectionConfig.tools} name lists. Invalid shapes are left
+ * for discovery.
+ */
+export function normalizeConnectionTools(tools: readonly string[]): string[] {
+  const unique: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of tools) {
+    const name = raw.trim();
+    if (name === "" || seen.has(name)) {
+      continue;
+    }
+    seen.add(name);
+    unique.push(name);
+  }
+  return unique;
+}
+
+/** True when `toolName` passes the connection's `tools` / `disallowedTools` filter. */
+export function connectionAllowsTool(
+  filter: {
+    tools?: readonly string[];
+    disallowedTools?: readonly string[];
+  },
+  toolName: string
+): boolean {
+  if (filter.tools !== undefined && !filter.tools.includes(toolName)) {
+    return false;
+  }
+  return (
+    filter.disallowedTools === undefined ||
+    !filter.disallowedTools.includes(toolName)
+  );
+}
+
 /**
  * A tool's declared {@link ToolEffect} — fixed, or decided per call from
  * validated input for tools that read or write depending on their arguments
@@ -1065,6 +1103,66 @@ export interface SkillConfig {
 
 export type SkillDefinition = SkillConfig & BrandedDefinition<"skill">;
 
+// ============================================================================
+// Extensions (agent/extensions/<ns>.ts | agent/extensions/<ns>/extension.ts)
+// ============================================================================
+
+/**
+ * Input to `defineExtension`, the `extension.ts` at the root of an
+ * agent-shaped tree (`tools/`, `skills/`, `lib/`).
+ */
+export interface ExtensionOptions<TConfig, TInput = TConfig> {
+  /** The tree's directory; pass `import.meta.dirname`. */
+  root: string;
+  /** What the extension adds; shown by `info`. */
+  description?: string;
+  /** Mount configuration schema. A consumer's settings are validated at mount. */
+  config?: z.ZodType<TConfig, z.ZodTypeDef, TInput>;
+}
+
+/**
+ * What `extension.ts` default-exports. A consumer calls it from
+ * `agent/extensions/<ns>.ts` to mount the extension with a configuration;
+ * the extension's own modules import it to read that configuration.
+ */
+export interface Extension<TConfig = undefined, TInput = TConfig>
+  extends ExtensionDeclaration {
+  (
+    ...args: undefined extends TInput ? [config?: TInput] : [config: TInput]
+  ): ExtensionMount;
+  /** The mounted configuration (schema defaults applied); throws before the mount. */
+  readonly config: TConfig;
+}
+
+/** The mount-independent part of an {@link Extension}. */
+export interface ExtensionDeclaration {
+  readonly root: string;
+  readonly description: string | undefined;
+}
+
+/** What `agent/extensions/<ns>.ts` default-exports. */
+export interface ExtensionMount extends BrandedDefinition<"extension"> {
+  readonly extension: ExtensionDeclaration;
+  readonly config: unknown;
+}
+
+/**
+ * `export default disableTool()` in a directory mount's `tools/<name>.ts`
+ * removes the extension's `<ns>__<name>`.
+ */
+export type DisabledToolDefinition = BrandedDefinition<"disabled-tool">;
+
+/** One mounted extension and the names it contributed. */
+export interface DiscoveredExtension {
+  /** Mount namespace: the filename stem or directory name under `agent/extensions/`. */
+  name: string;
+  description?: string;
+  /** Composed tool names (`<ns>__<name>`), overrides applied. */
+  tools: string[];
+  /** Composed skill names (`<ns>__<name>`), overrides applied. */
+  skills: string[];
+}
+
 // ============================================================================
 // MCP connections (agent/mcp-connections/*.ts)
 // ============================================================================
@@ -1213,19 +1311,38 @@ export type InlineStdioConnectionConfig = {
  * cloud VM.
  */
 export type ConnectionConfig = (
-  | Exclude<ConnectionTransport, { cursorAccount: true }>
-  | {
-      cursorAccount: true;
+  | ((
+      | Exclude<ConnectionTransport, { cursorAccount: true }>
+      | {
+          cursorAccount: true;
+          /**
+           * Which account connectors to expose.
+           *
+           * - Omit, pass `"*"`, or pass `["*"]` to forward **every** connected
+           *   HTTP/SSE server on the account (no per-connector allowlist).
+           * - Pass connector names as they appear in the Cursor account's MCP
+           *   config (e.g. `["Linear", "Notion"]`) to restrict the set.
+           */
+          servers?: string[] | "*";
+        }
+    ) & {
       /**
-       * Which account connectors to expose.
+       * Tool-name allowlist. Same shape as {@link AgentConfig.tools}:
+       * when set, only these MCP tool names (the server's `tools/list`
+       * names) are advertised and callable through `host.mcp`. Names
+       * the server does not list are omitted, not guessed.
+       *
+       * A list of names is an allowlist. An object of handlers authors
+       * TypeScript tools ({@link InlineStdioConnectionConfig}).
+       *
+       * On a model-visible connection this requires {@link advertiseTools}:
+       * an attached server would still expose every tool. On
+       * `host-connections/` it restricts `host.mcp` alone.
        *
-       * - Omit, pass `"*"`, or pass `["*"]` to forward **every** connected
-       *   HTTP/SSE server on the account (no per-connector allowlist).
-       * - Pass connector names as they appear in the Cursor account's MCP
-       *   config (e.g. `["Linear", "Notion"]`) to restrict the set.
+       * Combines with {@link disallowedTools} as deny-wins.
        */
-      servers?: string[] | "*";
-    }
+      tools?: readonly string[];
+    })
   | InlineStdioConnectionConfig
 ) & {
   /** Documentation only; shown in `info` output. */
@@ -1300,6 +1417,16 @@ export type ConnectionConfig = (
    * are the same.
    */
   effects?: ConnectionEffects;
+  /**
+   * Tool-name denylist. Same shape as the Cursor SDK's
+   * `disallowedTools`: when set, these MCP tool names are omitted from
+   * the advertised set and rejected on `host.mcp`. Combines with
+   * {@link ConnectionConfig.tools} as deny-wins.
+   *
+   * On a model-visible connection this requires {@link advertiseTools}.
+   * On `host-connections/` it restricts `host.mcp` alone.
+   */
+  disallowedTools?: readonly string[];
 };
 
 /**
@@ -1322,7 +1449,11 @@ export function isInlineStdioConnection(
 ): connection is InlineStdioConnectionConfig & {
   description?: string;
 } {
-  return "tools" in connection && connection.tools !== undefined;
+  return (
+    "tools" in connection &&
+    connection.tools !== undefined &&
+    !Array.isArray(connection.tools)
+  );
 }
 
 /**
@@ -1873,9 +2004,13 @@ export interface SendMessageOptions {
   dryRun?: boolean;
   /**
    * ISO-8601 instant with a timezone, frozen at create: the prompt states
-   * it, {@link ToolContext.now} returns it, and tools that declare
-   * {@link ToolConfig.timeArgs} refuse calls not bounded at or before it. A
-   * tool that declares nothing still reads the present.
+   * it, {@link ToolContext.now} returns it, and every tool call is checked
+   * against it — a relative time argument (`now-1h`), an absolute one after
+   * the instant, or an omitted window a vendor schema declares is refused so
+   * the model retries with explicit absolute bounds. Tools may also declare
+   * {@link ToolConfig.timeArgs} for precise per-field checking. The check
+   * reads arguments, not behavior: a tool that reads present state without a
+   * time argument still answers from the present.
    */
   asOf?: string;
   /**
@@ -2314,6 +2449,11 @@ export interface ChannelMeta {
    * by `info` so watched channels are auditable.
    */
   slackChannelPosts?: readonly string[];
+  /**
+   * Author-facing notices about deprecated options the pack still honored.
+   * Discovery surfaces each one as a `validate` warning on the channel file.
+   */
+  deprecations?: readonly string[];
 }
 
 export interface ChannelConfig<TState = JsonValue> {
@@ -2786,6 +2926,8 @@ export interface DiscoveredTool {
   advertised?: true;
   /** Name of the advertising connection an advertised tool came from. */
   connection?: string;
+  /** Mounted extension this tool came from; absent for `agent/tools/`. */
+  extension?: string;
   /**
    * Agent tools: script body materialized under
    * `.agent-serve/tools/<name>.sh`.
@@ -2804,6 +2946,8 @@ export interface DiscoveredSkill {
   markdown: string;
   /** Package-relative sibling files. */
   files: Record<string, SkillFileSource>;
+  /** Mounted extension this skill came from; absent for `agent/skills/`. */
+  extension?: string;
 }
 
 export interface DiscoveredConnection {
@@ -2819,6 +2963,16 @@ export interface DiscoveredConnection {
    * Absent means every listed tool is advertised.
    */
   effects?: readonly ToolEffect[];
+  /**
+   * Normalized tool-name allowlist from {@link ConnectionConfig.tools}.
+   * Absent means every listed tool is kept.
+   */
+  tools?: readonly string[];
+  /**
+   * Normalized tool-name denylist from
+   * {@link ConnectionConfig.disallowedTools}.
+   */
+  disallowedTools?: readonly string[];
 }
 
 export interface DiscoveredChannel {
@@ -2890,6 +3044,11 @@ export interface ResolvedAgent {
   architecture?: AgentArchitecture;
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
+  /**
+   * Mounted `agent/extensions/`. Their tools and skills are already merged
+   * into {@link tools} and {@link skills}; this records provenance.
+   */
+  extensions?: DiscoveredExtension[];
   connections: DiscoveredConnection[];
   /**
    * MCP connections from `agent/host-connections/`. Host tools and
@@ -2972,11 +3131,15 @@ export interface AgentProjectInfo {
     inputSchema: JsonSchemaObject;
   }>;
   skills: Array<{ name: string; description: string }>;
+  /** Mounted extensions and the tool / skill names each contributed. */
+  extensions: DiscoveredExtension[];
   connections: Array<{
     name: string;
     transport: string;
     advertiseTools?: boolean;
     effects?: readonly ToolEffect[];
+    tools?: readonly string[];
+    disallowedTools?: readonly string[];
     /**
      * Present only for `cursorAccount` connections: the connector-name
      * allowlist, or `"*"` for every connected server. Structured twin of the