@cursor/july 0.1.62 → 0.1.73

package/src/internal/advertise-tools.ts

@@ -0,0 +1,278 @@
+/**
+ * Advertised connection tools (`defineConnection({ advertiseTools: true })`).
+ *
+ * The session engine calls {@link resolveAdvertisedTools} while building
+ * every local turn: for each advertising connection it lists the server's
+ * tools and synthesizes a named 1:1 passthrough server tool per entry —
+ * the server's own names, descriptions, and live schemas — merged into the
+ * authored `agent/tools/` catalog. Because it runs at turn-build time it
+ * covers every way a turn starts (dispatcher sends, follow-ups, reminder
+ * fires that call the engine directly) and survives process restarts,
+ * since nothing is parked in memory between turns.
+ *
+ * Connections with per-session `auth` are listed and called through a
+ * one-off client carrying that session's headers (the registry's cached
+ * per-name client would leak one session's identity into another);
+ * auth-less connections go through the shared `host.mcp` registry, which
+ * also covers serve-resolved transports (Cursor account bridges, peers).
+ *
+ * Advertised names follow the Cursor-account MCP bridge
+ * (`packages/agent-serve/src/internal/cursor/account-mcp.ts`): slug
+ * `[^a-zA-Z0-9_-]` to `_`, collision suffixes `_2` / `_3`, and call the
+ * original advertised name. That is the same mapping `packages/agent`
+ * `normalizeMcpToolName` uses for IDE/Sand MCP tools. A listing failure
+ * still fails the turn rather than running it with a silently shrunken
+ * toolset.
+ */
+
+import type {
+  DiscoveredConnection,
+  DiscoveredTool,
+  HostMcpCallResult,
+  HostMcpToolInfo,
+  JsonSchemaObject,
+  ResolvedAgent,
+  SessionInfo,
+  ToolDefinition,
+} from "../types.js";
+import { brandDefinition } from "./brand.js";
+import type { HostMcpOneOff } from "./mcp-host.js";
+import {
+  sanitizeMcpToolName,
+  suffixMcpToolName,
+} from "./sanitize-mcp-tool-name.js";
+
+/**
+ * What the resolver needs from the host MCP registry: the shared cached
+ * clients for auth-less connections, and one-off clients (per-session
+ * headers, never cached) for auth'd ones. `McpHost` implements this.
+ */
+export interface AdvertiseHostMcp {
+  listTools(connectionName: string): Promise<HostMcpToolInfo[]>;
+  callTool(
+    connectionName: string,
+    toolName: string,
+    args?: Record<string, unknown>
+  ): Promise<HostMcpCallResult>;
+  oneOff(connection: DiscoveredConnection): HostMcpOneOff;
+}
+
+/**
+ * Model-facing advertised names after {@link sanitizeMcpToolName} — the
+ * same MCP-client shape the Cursor-account bridge documents
+ * (`^[a-zA-Z0-9_-]{1,128}$`). Authored `agent/tools/` filenames stay on
+ * discovery's stricter `NAME_PATTERN` (must start alphanumeric).
+ */
+export const ADVERTISED_TOOL_NAME_PATTERN: RegExp = /^[A-Za-z0-9_-]{1,128}$/;
+
+const ANY_OBJECT_SCHEMA: JsonSchemaObject = {
+  type: "object",
+  additionalProperties: true,
+};
+
+/** How one advertising connection is listed and called. */
+export interface AdvertisedToolSource {
+  listTools(): Promise<HostMcpToolInfo[]>;
+  callTool(
+    toolName: string,
+    args: Record<string, unknown>
+  ): Promise<HostMcpCallResult>;
+}
+
+/**
+ * Resolve the advertised tools for one session. Returns `[]` when no
+ * connection advertises; throws (failing the turn) when a listing fails
+ * or a definition is invalid.
+ */
+export async function resolveAdvertisedTools(args: {
+  agent: ResolvedAgent;
+  session: SessionInfo;
+  hostMcp: AdvertiseHostMcp;
+  /** Test seam; defaults to {@link sourceForConnection}. */
+  sourceFor?: (
+    connection: DiscoveredConnection,
+    session: SessionInfo,
+    hostMcp: AdvertiseHostMcp
+  ) => Promise<AdvertisedToolSource>;
+}): Promise<DiscoveredTool[]> {
+  const advertising = args.agent.connections.filter(
+    (connection) => connection.advertiseTools === true
+  );
+  if (advertising.length === 0) {
+    return [];
+  }
+  const sourceFor = args.sourceFor ?? sourceForConnection;
+  const claimed = new Set(args.agent.tools.map((tool) => tool.name));
+  const resolved: DiscoveredTool[] = [];
+  for (const connection of advertising) {
+    const source = await sourceFor(connection, args.session, args.hostMcp);
+    let listed: HostMcpToolInfo[];
+    try {
+      listed = await source.listTools();
+    } catch (error) {
+      throw new Error(
+        `Failed to list tools on advertised connection "${connection.name}": ${describeError(error)}`,
+        { cause: error }
+      );
+    }
+    const exposed = exposeListedTools(listed, claimed);
+    for (const { info, exposedName } of exposed) {
+      resolved.push(toDiscoveredTool(connection, info, exposedName, source));
+      claimed.add(exposedName);
+    }
+  }
+  return resolved;
+}
+
+/**
+ * The production source for one advertising connection: the shared
+ * `host.mcp` registry client for auth-less connections (which also covers
+ * serve-resolved transports — Cursor account bridges, peers), or a
+ * registry one-off with the session's headers substituted when the
+ * connection has per-session `auth`. The auth callback is evaluated once
+ * per turn, here; the one-off opens a fresh client per operation so one
+ * session's identity can never serve another's call.
+ */
+export async function sourceForConnection(
+  connection: DiscoveredConnection,
+  session: SessionInfo,
+  hostMcp: AdvertiseHostMcp
+): Promise<AdvertisedToolSource> {
+  if (connection.auth === undefined) {
+    return {
+      listTools: () => hostMcp.listTools(connection.name),
+      callTool: (toolName, callArgs) =>
+        hostMcp.callTool(connection.name, toolName, callArgs),
+    };
+  }
+  const transport = connection.transport;
+  if (!("url" in transport)) {
+    // Discovery rejects auth on non-URL transports; guard for callers that
+    // bypass discovery (hand-built projects).
+    throw new Error(
+      `Connection "${connection.name}" has per-session auth but no URL transport.`
+    );
+  }
+  const evaluated = await connection.auth(session);
+  return hostMcp.oneOff({
+    ...connection,
+    transport: {
+      ...transport,
+      headers: { ...transport.headers, ...evaluated.headers },
+    },
+  });
+}
+
+/**
+ * Same catalog rule as the Cursor-account bridge: slug illegal characters,
+ * then `_2` / `_3` … for colliders (including authored tools already in
+ * `claimed`). Suffix assignment is stable for a colliding group: sort by
+ * original advertised name, independent of `listTools` order.
+ */
+function exposeListedTools(
+  listed: HostMcpToolInfo[],
+  claimed: ReadonlySet<string>
+): Array<{ info: HostMcpToolInfo; exposedName: string }> {
+  const byBase = new Map<string, HostMcpToolInfo[]>();
+  for (const info of listed) {
+    const base = sanitizeMcpToolName(info.name);
+    const group = byBase.get(base);
+    if (group === undefined) {
+      byBase.set(base, [info]);
+    } else {
+      group.push(info);
+    }
+  }
+  const taken = new Set(claimed);
+  const exposedNameByInfo = new Map<HostMcpToolInfo, string>();
+  const sortedBases = [...byBase.keys()].sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0
+  );
+  for (const base of sortedBases) {
+    const group = byBase.get(base)!;
+    group.sort((left, right) =>
+      left.name < right.name ? -1 : left.name > right.name ? 1 : 0
+    );
+    group.forEach((info, index) => {
+      let suffixIndex = index;
+      let exposedName = suffixMcpToolName(base, suffixIndex);
+      while (taken.has(exposedName)) {
+        suffixIndex++;
+        exposedName = suffixMcpToolName(base, suffixIndex);
+      }
+      taken.add(exposedName);
+      exposedNameByInfo.set(info, exposedName);
+    });
+  }
+  return listed.map((info) => ({
+    info,
+    exposedName: exposedNameByInfo.get(info)!,
+  }));
+}
+
+function toDiscoveredTool(
+  connection: DiscoveredConnection,
+  info: HostMcpToolInfo,
+  exposedName: string,
+  source: AdvertisedToolSource
+): DiscoveredTool {
+  const description =
+    info.description === undefined || info.description.trim() === ""
+      ? `${info.name} — MCP tool on the "${connection.name}" connection, forwarded 1:1.`
+      : info.description;
+  const inputSchema = info.inputSchema ?? ANY_OBJECT_SCHEMA;
+  const outputSchema = info.outputSchema;
+  const definition: ToolDefinition = brandDefinition("tool", {
+    description,
+    inputSchema,
+    ...(outputSchema === undefined ? {} : { outputSchema }),
+    execute: async (input: Record<string, unknown>) =>
+      formatMcpToolResult(
+        connection.name,
+        info.name,
+        await source.callTool(info.name, input ?? {})
+      ),
+  } as unknown as ToolDefinition);
+  return {
+    name: exposedName,
+    description,
+    inputSchema,
+    ...(outputSchema === undefined ? {} : { outputSchema }),
+    execution: "server",
+    needsApproval: false,
+    definition,
+  };
+}
+
+/**
+ * Render an MCP call result for the model: text parts joined, non-text
+ * parts noted by type, `isError` surfaced as a thrown error so the turn
+ * records a tool error instead of error-shaped prose.
+ */
+export function formatMcpToolResult(
+  connectionName: string,
+  toolName: string,
+  result: HostMcpCallResult
+): string {
+  const parts = result.content.map((item) =>
+    item.type === "text" && typeof item.text === "string"
+      ? item.text
+      : `[${item.type} content omitted]`
+  );
+  const text = parts.join("\n").trim();
+  if (result.isError === true) {
+    throw new Error(
+      text === "" ? `${connectionName} tool ${toolName} failed` : text
+    );
+  }
+  if (text !== "") {
+    return text;
+  }
+  return result.structuredContent !== undefined
+    ? JSON.stringify(result.structuredContent, null, 2)
+    : "(empty result)";
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/internal/cli-deploy.ts

@@ -22,6 +22,7 @@ import {
   SIGN_IN_HINT,
 } from "./cursor/credentials.js";
 import { authorizeCursorAccountConnectors } from "./cursor-account-mcp-auth.js";
+import { readDeployTemplate } from "./cursor-agent-template.js";
 import {
   AgentServeDeployClient,
   type DeleteAccepted,
@@ -661,11 +662,20 @@ async function deployOne(
     ...(egressAllowedDomains.length === 0 ? {} : { egressAllowedDomains }),
     publicRoutePaths:
       publicRoutePaths.length === 0 ? undefined : publicRoutePaths,
+    // Deliberately NO manifest here: the control plane captures it from the
+    // provisioned engine (`GET /v1/manifest` after the health probe), which
+    // is the single write path for deploy manifests. `july manifest` remains
+    // available for local visibility only.
   };
 
   let accepted: DeployAccepted;
   try {
-    accepted = await ctx.client.deploy({ teamId: ctx.teamId, slug, source });
+    accepted = await ctx.client.deploy({
+      teamId: ctx.teamId,
+      slug,
+      source,
+      template: readDeployTemplate(dir),
+    });
   } catch (error) {
     return renderApiError(error, ctx.err);
   }

package/src/internal/cli-manifest.ts

@@ -0,0 +1,63 @@
+/**
+ * `july manifest` — print the offline deploy manifest (Wd-1 of
+ * `docs/agent-serve/agent-sdk-event-ingress-plan.md`).
+ *
+ * Loads the agent project from disk and emits the statically-derived
+ * metadata the control plane stores at deploy time: declared GitHub webhook
+ * events, egress domains, public routes, and the full `/v1/info` payload.
+ * Runs entirely offline — no VM, no engine, no network.
+ */
+
+import {
+  buildAgentDeployManifest,
+  parseAgentDeployManifest,
+} from "./deploy-manifest.js";
+import { isAgentProjectDir, loadAgentProject } from "./discovery.js";
+
+export interface CmdManifestOptions {
+  dir: string;
+  /** Compact single-line JSON (machine consumption); default pretty. */
+  json?: boolean;
+  /** Test seams. */
+  out?: (line: string) => void;
+  err?: (line: string) => void;
+}
+
+export async function cmdManifest(
+  options: CmdManifestOptions
+): Promise<number> {
+  const out = options.out ?? ((line: string) => process.stdout.write(line));
+  const err = options.err ?? ((line: string) => process.stderr.write(line));
+
+  if (!(await isAgentProjectDir(options.dir))) {
+    err(
+      `No agent project found at ${options.dir} (expected an agent.ts default-exporting defineAgent({ ... })).\n`
+    );
+    return 1;
+  }
+
+  const project = await loadAgentProject(options.dir);
+  for (const diagnostic of project.diagnostics) {
+    err(`${diagnostic.severity}: ${diagnostic.message}\n`);
+  }
+  if (project.diagnostics.some((d) => d.severity === "error")) {
+    return 1;
+  }
+
+  const manifest = buildAgentDeployManifest(project);
+  // Round-trip through the wire schema so `july manifest` can never emit
+  // something the control plane contract would reject.
+  if (
+    parseAgentDeployManifest(JSON.parse(JSON.stringify(manifest))) === undefined
+  ) {
+    err("internal error: generated manifest failed schema validation\n");
+    return 1;
+  }
+
+  out(
+    options.json === true
+      ? `${JSON.stringify(manifest)}\n`
+      : `${JSON.stringify(manifest, null, 2)}\n`
+  );
+  return 0;
+}

package/src/internal/cli-slack.ts

@@ -402,7 +402,16 @@ function writePendingAdminWait(
       ? poll.oauthAuthorizeUrl
       : undefined;
   ctx.err(`Waiting for a Slack admin to approve the app${appSuffix}.\n\n`);
-  if (requestUrl !== undefined) {
+  if (poll.approvalRequest === "pending") {
+    // Already in the admin queue: nothing to file, so no browser hop.
+    ctx.err(
+      ctx.dim(`  Approval request sent; workspace owners were notified.\n\n`)
+    );
+    if (requestUrl !== undefined) {
+      ctx.err(ctx.dim(`  Send a reminder from:\n\n`));
+      ctx.err(`  ${requestUrl}\n\n`);
+    }
+  } else if (requestUrl !== undefined) {
     ctx.err(
       ctx.dim(
         `  Slack will notify workspace owners once the request is in their queue.\n` +

package/src/internal/convert-automation/convert-workflow.ts

@@ -7,6 +7,7 @@
  */
 
 import { CLI_COMMAND_NAME, PACKAGE_NAME } from "../distribution.js";
+import { MEMORY_TS } from "../init-scaffold.js";
 import { pascalCase, SlugRegistry, slugify } from "./slug.js";
 import type {
   ActionJson,
@@ -128,7 +129,7 @@ export function convertWorkflow(
     hasSlackAction && emitSlackAccountConnection(automation, out);
 
   if (workflow.memoryEnabled === true) {
-    out.files.push({ path: "agent/hooks/memory.ts", contents: MEMORY_HOOK });
+    out.files.push({ path: "agent/hooks/memory.ts", contents: MEMORY_TS });
   }
 
   out.setupSteps.push(
@@ -1410,13 +1411,3 @@ function jsonComment(value: unknown): string[] {
 function dedupe(values: string[]): string[] {
   return [...new Set(values)];
 }
-
-/** Memory hook contents — identical to the `initProject` scaffold. */
-const MEMORY_HOOK = `// Journals every turn (timestamp, session, user message, result) so
-// future sessions can recall past work. The journal is shared across every
-// session — and every user — of this agent. Pass your own MemoryBackend to
-// change where memories live, or delete this file to opt out.
-import { memoryHook } from "${PACKAGE_NAME}/memory";
-
-export default memoryHook();
-`;