@cursor/july 0.1.9 → 0.1.11

package/src/evals.ts

@@ -315,6 +315,49 @@ export interface EvalRunSnapshot {
   };
 }
 
+/** One discovered eval datapoint as returned by {@link HostEvalsApi.list}. */
+export interface HostEvalListItem {
+  id: string;
+  fileId: string;
+  description?: string;
+  tags?: string[];
+}
+
+/** Config slice returned with {@link HostEvalsApi.list}. */
+export interface HostEvalListConfig {
+  maxConcurrency?: number;
+  timeoutMs?: number;
+  maxPlaygroundRuns: number;
+  /** True when `agent/storage.ts` declares an `evals` table. */
+  durableRuns: boolean;
+}
+
+/** Input for {@link HostEvalsApi.start} (same filters as `POST /v1/dev/evals/runs`). */
+export interface HostStartEvalRunInput {
+  filterIds?: string[];
+  tags?: string[];
+  /** Per-case timeout override (same semantics as CLI `--timeout-ms`). */
+  timeoutMs?: number;
+}
+
+/**
+ * Host-facing playground eval batches — the same surface as
+ * `/v1/dev/evals*` and `agentkit eval --prod`. Attached to
+ * {@link import("./types.js").HostContext.evals} by `serve`.
+ */
+export interface HostEvalsApi {
+  list(): Promise<{
+    evals: HostEvalListItem[];
+    config: HostEvalListConfig;
+  }>;
+  get(runId: string): Promise<EvalRunSnapshot | undefined>;
+  listRunsWithActive(): Promise<{
+    runs: EvalRunSnapshot[];
+    activeRunId?: string;
+  }>;
+  start(input?: HostStartEvalRunInput): Promise<EvalRunSnapshot>;
+}
+
 export interface EvalConfigFile {
   timeoutMs?: number;
   /**

package/src/index.ts

@@ -89,6 +89,8 @@ export {
   UnknownSessionError,
   UnknownToolError,
 } from "./internal/session-engine.js";
+export type { PromptTag } from "./prompt.js";
+export { prompt } from "./prompt.js";
 export type {
   ReminderBusyPolicy,
   ReminderCreateInput,
@@ -127,6 +129,7 @@ export {
   isCursorAccountTransport,
   isPeerConnectionTransport,
   isSymbolicConnectionTransport,
+  MAX_RUNNING_TURNS_LIMIT,
 } from "./types.js";
 
 /**

package/src/internal/cli-ax.ts

@@ -54,7 +54,7 @@ import { runSession } from "./run-client.js";
 import {
   fetchSessionEvents,
   formatSessionsTable,
-  listSessions,
+  listSessionsWithSource,
   resolvePreviousSessionId,
 } from "./sessions-client.js";
 import { createStreamProgress } from "./stream-progress.js";
@@ -1383,7 +1383,7 @@ export async function cmdSessions(options: AxCliOptions): Promise<number> {
     return target;
   }
   try {
-    const sessions = await listSessions({
+    const listed = await listSessionsWithSource({
       baseUrl: target.agentUrl,
       auth: {
         bearerToken: options.bearerToken,
@@ -1392,10 +1392,16 @@ export async function cmdSessions(options: AxCliOptions): Promise<number> {
       fetchImpl: options.fetchImpl,
     });
     if (options.json === true) {
-      process.stdout.write(`${JSON.stringify({ sessions }, null, 2)}\n`);
+      const payload =
+        listed.source === undefined
+          ? { sessions: listed.sessions }
+          : { sessions: listed.sessions, source: listed.source };
+      process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
       return 0;
     }
-    process.stdout.write(formatSessionsTable(sessions));
+    process.stdout.write(
+      formatSessionsTable(listed.sessions, { source: listed.source })
+    );
     return 0;
   } catch (error) {
     process.stderr.write(

package/src/internal/cli-mcp-oauth.ts

@@ -0,0 +1,254 @@
+/**
+ * `agentkit mcp oauth <connection> [--store]` for `defineConnection({ url, oauth: true })`.
+ */
+
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import { resolveDeployAuth } from "./cli-deploy.js";
+import { loadAgentProject } from "./discovery.js";
+import { CLI_COMMAND_NAME as CLI, LOG_PREFIX } from "./distribution.js";
+import {
+  createHostMcpOAuthProvider,
+  MCP_OAUTH_CALLBACK_URL,
+  mcpOauthSecretNames,
+  openBrowser,
+  waitForMcpOAuthCallback,
+} from "./mcp-oauth.js";
+import { resolveProdSlug } from "./resolve-prod-target.js";
+
+export type McpOauthCliOptions = {
+  dir: string;
+  connection: string;
+  /** Upsert MCP_OAUTH_* on the hosted deployment. */
+  store?: boolean;
+  slug?: string;
+  team?: string;
+  apiKey?: string;
+  err?: (text: string) => void;
+  out?: (text: string) => void;
+};
+
+function describe(error: unknown): string {
+  if (!(error instanceof Error)) {
+    return String(error);
+  }
+  const cause = error.cause;
+  if (!(cause instanceof Error)) {
+    return error.message;
+  }
+  const code =
+    "code" in cause && typeof cause.code === "string" ? cause.code : undefined;
+  const detail =
+    code === undefined ? cause.message : `${cause.message} (${code})`;
+  return `${error.message}: ${detail}`;
+}
+
+export async function cmdMcpOauth(
+  options: McpOauthCliOptions
+): Promise<number> {
+  const err = options.err ?? ((text) => process.stderr.write(text));
+  const out = options.out ?? ((text) => process.stdout.write(text));
+  const project = await loadAgentProject(options.dir);
+  const connection = project.agent.connections.find(
+    (entry) => entry.name === options.connection
+  );
+  if (connection === undefined) {
+    const known =
+      project.agent.connections.map((entry) => entry.name).join(", ") ||
+      "(none)";
+    err(
+      `${LOG_PREFIX} Unknown MCP connection "${options.connection}". Authored: ${known}.\n`
+    );
+    return 1;
+  }
+
+  const transport = connection.transport;
+  if (!("url" in transport) || transport.oauth !== true) {
+    err(
+      `${LOG_PREFIX} "${options.connection}" must be defineConnection({ url, oauth: true }).\n`
+    );
+    return 1;
+  }
+
+  out(
+    `${LOG_PREFIX} Authorizing "${options.connection}" (${transport.url})…\n`
+  );
+
+  let authorizationUrl: URL | undefined;
+  const provider = await createHostMcpOAuthProvider({
+    identifier: options.connection,
+    resourceUrl: transport.url,
+    onRedirect: (url) => {
+      authorizationUrl = url;
+    },
+  });
+
+  const client = new Client({ name: "agentkit-mcp-oauth", version: "0.1.0" });
+  const url = new URL(transport.url);
+  const requestInit =
+    transport.headers === undefined
+      ? undefined
+      : { headers: transport.headers };
+
+  const makeTransport = ():
+    | StreamableHTTPClientTransport
+    | SSEClientTransport => {
+    if (transport.type === "sse") {
+      return new SSEClientTransport(url, {
+        authProvider: provider,
+        requestInit,
+      });
+    }
+    return new StreamableHTTPClientTransport(url, {
+      authProvider: provider,
+      requestInit,
+    });
+  };
+
+  let mcpTransport = makeTransport();
+  let authorized = false;
+  try {
+    await client.connect(mcpTransport);
+    out(`${LOG_PREFIX} "${options.connection}" already authorized.\n`);
+    await client.close().catch(() => undefined);
+    authorized = true;
+  } catch (error) {
+    if (!(error instanceof UnauthorizedError)) {
+      err(
+        `${LOG_PREFIX} Failed to connect to "${options.connection}": ${describe(error)}\n`
+      );
+      return 1;
+    }
+  }
+
+  if (!authorized) {
+    const redirect = authorizationUrl ?? provider.lastRedirectUrl;
+    if (redirect === undefined) {
+      err(
+        `${LOG_PREFIX} Auth required but no authorization URL was provided.\n`
+      );
+      return 1;
+    }
+
+    out(`${LOG_PREFIX} Open if needed:\n  ${redirect.toString()}\n`);
+    out(`${LOG_PREFIX} Waiting on ${MCP_OAUTH_CALLBACK_URL}…\n`);
+    openBrowser(redirect.toString());
+
+    let callback: Awaited<ReturnType<typeof waitForMcpOAuthCallback>>;
+    try {
+      callback = await waitForMcpOAuthCallback();
+    } catch (error) {
+      err(`${LOG_PREFIX} OAuth callback failed: ${describe(error)}\n`);
+      return 1;
+    }
+
+    try {
+      await mcpTransport.finishAuth(callback.code);
+    } catch (error) {
+      err(`${LOG_PREFIX} Token exchange failed: ${describe(error)}\n`);
+      return 1;
+    }
+
+    mcpTransport = makeTransport();
+    try {
+      await client.connect(mcpTransport);
+      const tools = await client.listTools();
+      out(
+        `${LOG_PREFIX} Authorized "${options.connection}" (${tools.tools.length} tools). Local tokens in the agent-serve config dir.\n`
+      );
+      await client.close().catch(() => undefined);
+    } catch (error) {
+      err(
+        `${LOG_PREFIX} Reconnect failed: ${describe(error)}. Re-run \`${CLI} mcp oauth ${options.connection}\`.\n`
+      );
+      return 1;
+    }
+  }
+
+  if (options.store !== true) {
+    return 0;
+  }
+  return storeOauthSecrets({
+    connection: options.connection,
+    dir: options.dir,
+    slug: options.slug,
+    team: options.team,
+    apiKey: options.apiKey,
+    tokens: provider.tokens(),
+    clientId: provider.clientInformation()?.client_id,
+    err,
+    out,
+  });
+}
+
+async function storeOauthSecrets(args: {
+  connection: string;
+  dir: string;
+  slug?: string;
+  team?: string;
+  apiKey?: string;
+  tokens: OAuthTokens | undefined;
+  clientId: string | undefined;
+  err: (text: string) => void;
+  out: (text: string) => void;
+}): Promise<number> {
+  const tokens = args.tokens;
+  if (tokens === undefined || tokens.access_token.trim() === "") {
+    args.err(
+      `${LOG_PREFIX} No access token to store for "${args.connection}".\n`
+    );
+    return 1;
+  }
+
+  let slug: string;
+  try {
+    slug = resolveProdSlug({ dir: args.dir, slug: args.slug });
+  } catch (error) {
+    args.err(`${LOG_PREFIX} ${describe(error)}\n`);
+    return 1;
+  }
+
+  const auth = await resolveDeployAuth({
+    team: args.team,
+    apiKey: args.apiKey,
+    err: args.err,
+  });
+  if (typeof auth === "number") {
+    return auth;
+  }
+
+  const names = mcpOauthSecretNames(args.connection);
+  const secrets: Array<{ name: string; value: string }> = [
+    { name: names.accessToken, value: tokens.access_token },
+  ];
+  if (
+    tokens.refresh_token !== undefined &&
+    tokens.refresh_token.trim() !== ""
+  ) {
+    secrets.push({ name: names.refreshToken, value: tokens.refresh_token });
+  }
+  if (args.clientId !== undefined && args.clientId.trim() !== "") {
+    secrets.push({ name: names.clientId, value: args.clientId });
+  }
+
+  try {
+    const secretNames = await auth.client.setSecrets({
+      teamId: auth.teamId,
+      slug,
+      secrets,
+    });
+    args.out(
+      `${LOG_PREFIX} Stored on ${slug}: ${secrets.map((s) => s.name).join(", ")}.\n` +
+        `${LOG_PREFIX} Secrets now: ${secretNames.join(", ")}. Next deploy picks them up.\n`
+    );
+    return 0;
+  } catch (error) {
+    args.err(
+      `${LOG_PREFIX} Failed to store secrets on ${slug}: ${describe(error)}\n`
+    );
+    return 1;
+  }
+}

package/src/internal/cli-mcp.ts

@@ -89,7 +89,10 @@ export interface McpCliOptions {
 
 export async function cmdMcp(
   subcommand: string | undefined,
-  options: McpCliOptions
+  options: McpCliOptions & {
+    oauthConnection?: string;
+    store?: boolean;
+  }
 ): Promise<number> {
   const err = options.err ?? defaultErr;
   if (subcommand === undefined) {
@@ -98,9 +101,29 @@ export async function cmdMcp(
   if (subcommand === "install") {
     return cmdMcpInstall(options);
   }
+  if (subcommand === "oauth") {
+    const connection = options.oauthConnection;
+    if (connection === undefined || connection.trim() === "") {
+      err(
+        `Usage: ${CLI} mcp oauth <connection> [--dir .] [--store] [--slug <slug>] [--team <id>]\n` +
+          `Authorize defineConnection({ url, oauth: true }) (host PKCE).\n` +
+          `--store upserts MCP_OAUTH_<NAME>_* secrets on the hosted deployment.\n`
+      );
+      return 1;
+    }
+    const { cmdMcpOauth } = await import("./cli-mcp-oauth.js");
+    return cmdMcpOauth({
+      dir: options.dir,
+      connection,
+      store: options.store,
+      slug: options.slug,
+      team: options.team,
+      apiKey: options.apiKey,
+    });
+  }
   err(
     `Unknown mcp subcommand "${subcommand}".\n` +
-      `Usage: ${CLI} mcp [install] --prod [--slug <slug>] | --url <baseUrl>\n`
+      `Usage: ${CLI} mcp [install|oauth <connection>] --prod [--slug <slug>] | --url <baseUrl>\n`
   );
   return 1;
 }

package/src/internal/cursor/account-mcp.ts

@@ -213,48 +213,89 @@ export class CursorAccountMcpBridge {
 
   /**
    * Startup DX: log the account's connector statuses for `refs` without
-   * blocking serve startup. Surfaces "needsAuth" connectors (authorize in
-   * Cursor) and filters that matched nothing (typo'd connector names).
+   * blocking serve startup. Surfaces "needsAuth" / "error" connectors with
+   * remediation hints (and a backend probe detail for `error`), and filters
+   * that matched nothing (typo'd connector names).
+   *
+   * Returns a promise that settles when every ref's log lines are written —
+   * callers may ignore it; tests can await it.
    */
-  logPreflight(refs: CursorAccountConnectionRef[]): void {
-    for (const ref of refs) {
-      void this.getCatalog(ref)
-        .then((catalog) => {
-          const summary = catalog.servers
-            .map(
-              (server) =>
-                `${server.serverIdentifier} (${
-                  server.status === "connected"
-                    ? `${server.tools.length} tools`
-                    : server.status
-                })`
-            )
-            .join(", ");
-          this.logger(
-            `[agentkit] Cursor account MCP connection "${ref.name}": ${
-              catalog.servers.length === 0
-                ? "no matching connectors on this account — connect servers in Cursor (dashboard → MCP) or fix the `servers` filter"
-                : summary
-            }`
-          );
-          const needsAuth = catalog.servers.filter(
-            (server) => server.status === "needsAuth"
-          );
-          if (needsAuth.length > 0) {
-            this.logger(
-              `[agentkit] Cursor account MCP connection "${ref.name}": ${needsAuth
-                .map((server) => server.serverIdentifier)
-                .join(
-                  ", "
-                )} need re-authorization in Cursor before their tools appear`
+  logPreflight(refs: CursorAccountConnectionRef[]): Promise<void> {
+    return Promise.all(refs.map((ref) => this.runPreflight(ref))).then(
+      () => undefined
+    );
+  }
+
+  private async runPreflight(ref: CursorAccountConnectionRef): Promise<void> {
+    try {
+      const catalog = await this.getCatalog(ref);
+      if (catalog.servers.length === 0) {
+        this.logger(
+          `[agentkit] Cursor account MCP connection "${ref.name}": no matching connectors on this account — connect servers in Cursor (dashboard → MCP) or fix the \`servers\` filter`
+        );
+        return;
+      }
+
+      const errorDetails = new Map<string, string>();
+      await Promise.all(
+        catalog.servers
+          .filter((server) => server.status === "error")
+          .map(async (server) => {
+            const detail = await diagnoseConnectorError(
+              this.client,
+              server.serverIdentifier
             );
-          }
-        })
-        .catch((error: unknown) => {
-          this.logger(
-            `[agentkit] Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`
-          );
-        });
+            if (detail !== undefined) {
+              errorDetails.set(server.serverIdentifier, detail);
+            }
+          })
+      );
+
+      const summary = catalog.servers
+        .map((server) =>
+          formatServerStatusSummary(
+            server,
+            errorDetails.get(server.serverIdentifier)
+          )
+        )
+        .join(", ");
+      this.logger(
+        `[agentkit] Cursor account MCP connection "${ref.name}": ${summary}`
+      );
+
+      const needsAuth = catalog.servers.filter(
+        (server) => server.status === "needsAuth"
+      );
+      if (needsAuth.length > 0) {
+        this.logger(
+          `[agentkit] Cursor account MCP connection "${ref.name}": ${needsAuth
+            .map((server) => server.serverIdentifier)
+            .join(
+              ", "
+            )} need re-authorization in Cursor (dashboard → MCP / Settings → MCP) before their tools appear`
+        );
+      }
+
+      const errored = catalog.servers.filter(
+        (server) => server.status === "error"
+      );
+      if (errored.length > 0) {
+        const details = errored
+          .map((server) => {
+            const detail = errorDetails.get(server.serverIdentifier);
+            return detail === undefined
+              ? server.serverIdentifier
+              : `${server.serverIdentifier} (${detail})`;
+          })
+          .join("; ");
+        this.logger(
+          `[agentkit] Cursor account MCP connection "${ref.name}": ${details} — Cursor backend could not use this connector (not a missing agentkit login). Re-check the server in Cursor dashboard → MCP, confirm the URL is healthy, and retry after the backend can reach it`
+        );
+      }
+    } catch (error: unknown) {
+      this.logger(
+        `[agentkit] Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`
+      );
     }
   }
 
@@ -283,13 +324,22 @@ export class CursorAccountMcpBridge {
       const tool = await this.findTool(ref, request.params.name);
       if (tool === undefined) {
         const catalog = await this.getCatalog(ref);
+        const unhealthy = catalog.servers.filter(
+          (server) => server.status !== "connected"
+        );
+        const statusHint =
+          unhealthy.length === 0
+            ? ""
+            : ` Unhealthy connectors: ${unhealthy
+                .map((server) => `${server.serverIdentifier}=${server.status}`)
+                .join(", ")}.`;
         return {
           content: [
             {
               type: "text",
               text: `Unknown tool "${request.params.name}". Available: ${
                 catalog.tools.map((t) => t.exposedName).join(", ") || "(none)"
-              }.`,
+              }.${statusHint}`,
             },
           ],
           isError: true,
@@ -470,3 +520,65 @@ function trimTrailingSlash(url: string): string {
 function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+/** One-line status for the preflight summary (`name (12 tools)` / `name (error: …)`). */
+export function formatServerStatusSummary(
+  server: AccountMcpServer,
+  errorDetail?: string
+): string {
+  switch (server.status) {
+    case "connected":
+      return `${server.serverIdentifier} (${server.tools.length} tools)`;
+    case "needsAuth":
+      return `${server.serverIdentifier} (needsAuth — re-authorize in Cursor)`;
+    case "loading":
+      return `${server.serverIdentifier} (loading)`;
+    case "error": {
+      const detail =
+        errorDetail === undefined || errorDetail.trim() === ""
+          ? "backend could not reach connector"
+          : errorDetail.trim();
+      return `${server.serverIdentifier} (error: ${detail})`;
+    }
+    default:
+      return `${server.serverIdentifier} (${server.status})`;
+  }
+}
+
+/**
+ * Best-effort detail for an `error`-status connector. ListSandMcpTools only
+ * returns the status enum today, so probe ExecuteSandMcpTool (ping) and surface
+ * the backend failure text (e.g. `HTTP MCP tool execution failed: fetch failed`).
+ */
+export async function diagnoseConnectorError(
+  client: Pick<CursorBackendClient, "executeAccountMcpTool">,
+  serverIdentifier: string
+): Promise<string | undefined> {
+  try {
+    const result = await client.executeAccountMcpTool({
+      serverIdentifier,
+      // Conventional health tool; even a tool-not-found path usually still
+      // surfaces the same transport failure when the connector is down.
+      toolName: `${serverIdentifier}-ping`,
+      args: {},
+    });
+    const text = result.content
+      .filter(
+        (part): part is { type: "text"; text: string } => part.type === "text"
+      )
+      .map((part) => part.text.trim())
+      .filter((part) => part.length > 0)
+      .join(" ");
+    if (result.isError) {
+      return text.length > 0
+        ? text
+        : "backend reported an error with no detail";
+    }
+    // Listing said error but ping succeeded — surface that inconsistency.
+    return text.length > 0
+      ? `listing reported error but probe succeeded: ${text}`
+      : "listing reported error but probe succeeded";
+  } catch (error: unknown) {
+    return describeError(error);
+  }
+}