@cursor/july 0.1.19 → 0.1.21

package/src/internal/session-engine.coalesce.test.ts

@@ -0,0 +1,169 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { httpChannel } from "../channels.js";
+import type { AgentProject, RunnerTurnRequest, TurnOutcome } from "../types.js";
+import type { AgentRunner } from "./sdk-runner.js";
+import { SessionEngine } from "./session-engine.js";
+
+function testProject(rootDir: string): AgentProject {
+  return {
+    rootDir,
+    agentDir: join(rootDir, "agent"),
+    name: "coalesce-test",
+    agent: {
+      name: "coalesce-test",
+      runtime: "local",
+      instructions: "Test agent.",
+      tools: [],
+      skills: [],
+      connections: [],
+      subagents: [],
+      seedFiles: [],
+    },
+    httpChannel: httpChannel(),
+    channels: [],
+    schedules: [],
+    hooks: [],
+    abs: [],
+    diagnostics: [],
+  };
+}
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function waitFor(
+  predicate: () => boolean,
+  label: string,
+  timeoutMs = 2000
+): Promise<void> {
+  const started = Date.now();
+  while (!predicate()) {
+    if (Date.now() - started > timeoutMs) {
+      throw new Error(`timed out waiting for ${label}`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+describe("SessionEngine coalesce admission", () => {
+  it("enqueues busy follow-ups and drains one coalesced turn", async () => {
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-coalesce-"));
+    cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+
+    let releaseFirst!: () => void;
+    const firstGate = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    const seen: string[] = [];
+    const runner: AgentRunner = {
+      runTurn: async (request: RunnerTurnRequest): Promise<TurnOutcome> => {
+        seen.push(request.prompt);
+        if (seen.length === 1) {
+          await firstGate;
+          return { status: "finished", result: "first-done" };
+        }
+        return { status: "finished", result: "coalesced-done" };
+      },
+    };
+
+    const engine = new SessionEngine({
+      project: testProject(stateRoot),
+      stateRoot,
+      runner,
+    });
+    cleanups.push(async () => {
+      releaseFirst();
+      await engine.close();
+    });
+
+    const session = await engine.send("http", "first", {
+      auth: null,
+      continuationToken: "thread-1",
+    });
+    expect(session.coalesced).toBeUndefined();
+    // send() returns once the turn is admitted; runTurn may still be
+    // scaffolding the workspace.
+    await waitFor(() => seen.length >= 1, "first runTurn");
+
+    const second = await engine.send("http", "second-ask", {
+      auth: null,
+      continuationToken: "thread-1",
+      admission: "coalesce",
+      coalesceSourceTs: "2.0",
+    });
+    expect(second.coalesced).toBe(true);
+    expect(seen).toHaveLength(1);
+
+    const third = await engine.send("http", "third-ask", {
+      auth: null,
+      continuationToken: "thread-1",
+      admission: "coalesce",
+      coalesceSourceTs: "3.0",
+    });
+    expect(third.coalesced).toBe(true);
+
+    releaseFirst();
+    await session.waitForCompletion();
+    // Drain starts the coalesced follow-up; wait for it.
+    await second.waitForCompletion();
+
+    expect(seen.length).toBeGreaterThanOrEqual(2);
+    const followUp = seen[1] ?? "";
+    expect(followUp).toContain("ANSWER-EACH");
+    expect(followUp).toContain("second-ask");
+    expect(followUp).toContain("third-ask");
+    // First turn was not interrupted for the coalesced follow-ups.
+    expect(seen[0]?.endsWith("first") || seen[0]?.includes("first")).toBe(true);
+  });
+
+  it("keeps preempt semantics by default", async () => {
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-preempt-"));
+    cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+
+    let firstAborted = false;
+    const seen: string[] = [];
+    const runner: AgentRunner = {
+      runTurn: async (request: RunnerTurnRequest): Promise<TurnOutcome> => {
+        seen.push(request.prompt);
+        if (request.prompt.endsWith("first")) {
+          await new Promise<void>((resolve) => {
+            if (request.signal?.aborted === true) {
+              resolve();
+              return;
+            }
+            request.signal?.addEventListener("abort", () => resolve(), {
+              once: true,
+            });
+          });
+          firstAborted = true;
+          return { status: "cancelled" };
+        }
+        return { status: "finished", result: "second-done" };
+      },
+    };
+
+    const engine = new SessionEngine({
+      project: testProject(stateRoot),
+      stateRoot,
+      runner,
+    });
+    cleanups.push(() => engine.close());
+
+    const session = await engine.send("http", "first", { auth: null });
+    const follow = await engine.send("http", "second", {
+      auth: null,
+      continuationToken: session.continuationToken ?? undefined,
+    });
+    await follow.waitForCompletion();
+    expect(firstAborted).toBe(true);
+    expect(seen[1]).toBe("second");
+  });
+});

package/src/internal/session-engine.concurrency.test.ts

@@ -0,0 +1,250 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { httpChannel } from "../channels.js";
+import type {
+  AgentProject,
+  RunnerTurnRequest,
+  SessionEvent,
+  TurnOutcome,
+} from "../types.js";
+import type { AgentRunner } from "./sdk-runner.js";
+import { SessionEngine } from "./session-engine.js";
+
+function testProject(rootDir: string, maxRunningTurns: number): AgentProject {
+  return {
+    rootDir,
+    agentDir: join(rootDir, "agent"),
+    name: "concurrency-test",
+    agent: {
+      name: "concurrency-test",
+      runtime: "local",
+      instructions: "Test agent.",
+      concurrency: { maxRunningTurns },
+      tools: [],
+      skills: [],
+      connections: [],
+      subagents: [],
+      seedFiles: [],
+    },
+    httpChannel: httpChannel(),
+    channels: [],
+    schedules: [],
+    hooks: [],
+    abs: [],
+    diagnostics: [],
+  };
+}
+
+/**
+ * Runner whose turns block until released per message. First-turn prompts
+ * carry the framework context block, so turns are keyed by prompt suffix.
+ */
+function gatedRunner() {
+  const started: string[] = [];
+  const releases = new Map<string, () => void>();
+  const runner: AgentRunner = {
+    runTurn: async (request: RunnerTurnRequest): Promise<TurnOutcome> => {
+      const key = request.prompt.split("\n").at(-1) ?? request.prompt;
+      started.push(key);
+      let cancelled = false;
+      await new Promise<void>((resolve) => {
+        releases.set(key, resolve);
+        if (request.signal?.aborted === true) {
+          cancelled = true;
+          resolve();
+          return;
+        }
+        request.signal?.addEventListener(
+          "abort",
+          () => {
+            cancelled = true;
+            resolve();
+          },
+          { once: true }
+        );
+      });
+      return cancelled
+        ? { status: "cancelled" }
+        : { status: "finished", result: `${key}-done` };
+    },
+  };
+  return {
+    runner,
+    started,
+    release: (key: string) => releases.get(key)?.(),
+  };
+}
+
+async function waitUntil(
+  predicate: () => boolean,
+  label: string,
+  timeoutMs = 5_000
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() > deadline) {
+      throw new Error(`timed out waiting for ${label}`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+function eventTypes(events: SessionEvent[]): string[] {
+  return events.map((event) => event.type);
+}
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+describe("SessionEngine maxRunningTurns", () => {
+  it("caps concurrent turns and starts queued turns FIFO as slots free", async () => {
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-conc-"));
+    cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+
+    const { runner, started, release } = gatedRunner();
+    const engine = new SessionEngine({
+      project: testProject(stateRoot, 2),
+      stateRoot,
+      runner,
+    });
+    cleanups.push(() => engine.close());
+
+    const a = await engine.send("http", "turn-a", { auth: null });
+    const b = await engine.send("http", "turn-b", { auth: null });
+    const c = await engine.send("http", "turn-c", { auth: null });
+    const d = await engine.send("http", "turn-d", { auth: null });
+
+    await waitUntil(() => started.length === 2, "two running turns");
+    expect(started).toEqual(["turn-a", "turn-b"]);
+
+    // The overflow turns are durably marked queued, in arrival order.
+    const queuedC = (await engine.listEvents(c.id)).find(
+      (event) => event.type === "turn.queued"
+    );
+    expect(queuedC?.data).toEqual({ position: 1, maxRunningTurns: 2 });
+    const queuedD = (await engine.listEvents(d.id)).find(
+      (event) => event.type === "turn.queued"
+    );
+    expect(queuedD?.data).toEqual({ position: 2, maxRunningTurns: 2 });
+
+    // Queued sessions count as running (busy) and report queued: true.
+    const summaries = await engine.listSessions(null, { includeAll: true });
+    const summaryOf = (id: string) =>
+      summaries.find((summary) => summary.sessionId === id);
+    expect(summaryOf(a.id)).toMatchObject({ running: true, queued: false });
+    expect(summaryOf(c.id)).toMatchObject({ running: true, queued: true });
+    expect(summaryOf(d.id)).toMatchObject({ running: true, queued: true });
+
+    // Freeing one slot starts exactly the oldest queued turn.
+    release("turn-a");
+    await waitUntil(() => started.length === 3, "third turn started");
+    expect(started).toEqual(["turn-a", "turn-b", "turn-c"]);
+
+    release("turn-b");
+    await waitUntil(() => started.length === 4, "fourth turn started");
+    expect(started).toEqual(["turn-a", "turn-b", "turn-c", "turn-d"]);
+
+    release("turn-c");
+    release("turn-d");
+    for (const session of [a, b, c, d]) {
+      const outcome = await session.waitForCompletion();
+      expect(outcome.status).toBe("finished");
+    }
+
+    // A queued turn's stream shows queued → started → completed.
+    const cTypes = eventTypes(await engine.listEvents(c.id));
+    expect(cTypes.indexOf("turn.queued")).toBeGreaterThan(
+      cTypes.indexOf("message.received")
+    );
+    expect(cTypes.indexOf("turn.started")).toBeGreaterThan(
+      cTypes.indexOf("turn.queued")
+    );
+    expect(cTypes).toContain("turn.completed");
+
+    // An unqueued turn never records turn.queued.
+    expect(eventTypes(await engine.listEvents(a.id))).not.toContain(
+      "turn.queued"
+    );
+  });
+
+  it("a follow-up preempts a queued turn and re-queues", async () => {
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-conc-pre-"));
+    cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+
+    const { runner, started, release } = gatedRunner();
+    const engine = new SessionEngine({
+      project: testProject(stateRoot, 1),
+      stateRoot,
+      runner,
+    });
+    cleanups.push(() => engine.close());
+
+    await engine.send("http", "turn-a", { auth: null });
+    const b = await engine.send("http", "turn-b", {
+      auth: null,
+      continuationToken: "sticky-b",
+    });
+    await waitUntil(() => started.length === 1, "first turn running");
+
+    // Preempt B while it waits for a slot; the queued turn is cancelled
+    // without ever reaching the runner and the follow-up queues behind.
+    const followUp = await engine.send("http", "turn-b2", {
+      auth: null,
+      continuationToken: "sticky-b",
+    });
+    expect(followUp.id).toBe(b.id);
+
+    release("turn-a");
+    await waitUntil(() => started.length === 2, "follow-up started");
+    expect(started).toEqual(["turn-a", "turn-b2"]);
+
+    release("turn-b2");
+    const outcome = await followUp.waitForCompletion();
+    expect(outcome.status).toBe("finished");
+    expect(outcome.result).toBe("turn-b2-done");
+
+    const events = await engine.listEvents(b.id);
+    const turnOne = events.filter((event) => event.turnId === "turn_1");
+    expect(eventTypes(turnOne)).not.toContain("turn.started");
+    const failed = turnOne.find((event) => event.type === "turn.failed");
+    expect((failed?.data as { message?: string } | undefined)?.message).toBe(
+      "turn interrupted"
+    );
+    const turnTwo = events.filter((event) => event.turnId === "turn_2");
+    expect(eventTypes(turnTwo)).toContain("turn.queued");
+    expect(eventTypes(turnTwo)).toContain("turn.completed");
+  });
+
+  it("interrupt() cancels a queued turn without running it", async () => {
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-conc-int-"));
+    cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+
+    const { runner, started, release } = gatedRunner();
+    const engine = new SessionEngine({
+      project: testProject(stateRoot, 1),
+      stateRoot,
+      runner,
+    });
+    cleanups.push(() => engine.close());
+
+    const a = await engine.send("http", "turn-a", { auth: null });
+    const b = await engine.send("http", "turn-b", { auth: null });
+    await waitUntil(() => started.length === 1, "first turn running");
+
+    expect(await engine.interrupt(b.id)).toBe(true);
+    const outcome = await b.waitForCompletion();
+    expect(outcome.status).toBe("cancelled");
+
+    release("turn-a");
+    expect((await a.waitForCompletion()).status).toBe("finished");
+    // The cancelled queued turn never reached the runner.
+    expect(started).toEqual(["turn-a"]);
+  });
+});

package/src/internal/session-engine.host-oauth-mcp.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Host-OAuth MCP connections (`defineConnection({ url, oauth: true })`) hold
+ * their tokens on the serve host, so they belong to local turns and host
+ * tools. Handing one to a cloud turn also fails the turn outright: the cloud
+ * API rejects the `oauth` key with `[validation_error] Unrecognized key(s) in
+ * object: 'oauth'`.
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { httpChannel } from "../channels.js";
+import type {
+  AgentProject,
+  AgentRuntime,
+  ConnectionTransport,
+  DiscoveredConnection,
+  RunnerTurnRequest,
+  TurnOutcome,
+} from "../types.js";
+import type { AgentRunner } from "./sdk-runner.js";
+import { SessionEngine } from "./session-engine.js";
+
+const ANYTOOL: DiscoveredConnection = {
+  name: "anytool",
+  transport: { url: "https://anytool.example.com/mcp", oauth: true },
+};
+
+const PLAIN: DiscoveredConnection = {
+  name: "weather",
+  transport: { url: "https://weather.example.com/mcp" },
+};
+
+function testProject(
+  rootDir: string,
+  runtime: AgentRuntime,
+  connections: DiscoveredConnection[]
+): AgentProject {
+  return {
+    rootDir,
+    agentDir: join(rootDir, "agent"),
+    name: "host-oauth-test",
+    agent: {
+      name: "host-oauth-test",
+      description: "Exercises host-OAuth MCP connections.",
+      runtime,
+      ...(runtime === "cloud"
+        ? { cloud: { repos: [{ url: "https://github.com/org/repo" }] } }
+        : {}),
+      tools: [],
+      skills: [],
+      connections,
+      subagents: [],
+      seedFiles: [],
+    },
+    httpChannel: httpChannel(),
+    channels: [],
+    schedules: [],
+    hooks: [],
+    abs: [],
+    diagnostics: [],
+  };
+}
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function turnMcpServers(
+  runtime: AgentRuntime,
+  connections: DiscoveredConnection[]
+): Promise<Record<string, ConnectionTransport>> {
+  const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-host-oauth-"));
+  cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+  const requests: RunnerTurnRequest[] = [];
+  const runner: AgentRunner = {
+    runTurn: async (request): Promise<TurnOutcome> => {
+      requests.push(request);
+      return { status: "finished", result: "ok" };
+    },
+  };
+  const engine = new SessionEngine({
+    project: testProject(stateRoot, runtime, connections),
+    stateRoot,
+    runner,
+  });
+  cleanups.push(() => engine.close());
+  const session = await engine.send("http", "hello", { auth: null });
+  await session.waitForCompletion();
+  return requests[0]?.mcpServers ?? {};
+}
+
+describe("host-OAuth MCP connections per runtime", () => {
+  it("hands the connection to local turns", async () => {
+    const servers = await turnMcpServers("local", [ANYTOOL, PLAIN]);
+    expect(servers.anytool).toEqual(ANYTOOL.transport);
+    expect(servers.weather).toEqual(PLAIN.transport);
+  });
+
+  it("omits the connection from cloud turns, keeping the rest", async () => {
+    const servers = await turnMcpServers("cloud", [ANYTOOL, PLAIN]);
+    expect(servers.anytool).toBeUndefined();
+    expect(servers.weather).toEqual(PLAIN.transport);
+  });
+});