|
9 | 9 | buildCursorToolGuidanceSystemNote, |
10 | 10 | CURSOR_EXEC_COMMAND_INPUT_SCHEMA, |
11 | 11 | cursorRequestAdvertisesApplyPatch, |
| 12 | + cursorRequestUsesCodeMode, |
| 13 | + isCursorCodeModeExecTool, |
12 | 14 | cursorToolArgNormalizeSchema, |
13 | 15 | cursorToolInputSchema, |
14 | 16 | cursorToolWireName, |
@@ -411,3 +413,72 @@ describe("Cursor tool definitions", () => { |
411 | 413 | expect(allowedNote).not.toContain("`mcp__fs__read_file`"); |
412 | 414 | }); |
413 | 415 | }); |
| 416 | + |
| 417 | +describe("Cursor code mode tool guidance", () => { |
| 418 | + const codeModeExec = (): OcxTool => ({ |
| 419 | + name: "exec", |
| 420 | + description: "Run JavaScript code to orchestrate tool calls. Nested tools are available on the global `tools` object.", |
| 421 | + parameters: {}, |
| 422 | + freeform: true, |
| 423 | + }); |
| 424 | + |
| 425 | + test("detects code mode only when freeform exec has no bare shell bridge", () => { |
| 426 | + expect(cursorRequestUsesCodeMode([codeModeExec()])).toBe(true); |
| 427 | + expect(isCursorCodeModeExecTool(codeModeExec())).toBe(true); |
| 428 | + |
| 429 | + // A non-freeform `exec` is not code mode. |
| 430 | + expect(cursorRequestUsesCodeMode([{ name: "exec", description: "Run", parameters: {} }])).toBe(false); |
| 431 | + // A bare shell bridge alongside it means the flat-catalog guidance still applies. |
| 432 | + expect(cursorRequestUsesCodeMode([codeModeExec(), { name: "exec_command", description: "Run", parameters: {} }])).toBe(false); |
| 433 | + expect(cursorRequestUsesCodeMode([{ name: "exec_command", description: "Run", parameters: {} }])).toBe(false); |
| 434 | + expect(cursorRequestUsesCodeMode(undefined)).toBe(false); |
| 435 | + // Tool choice that hides exec also hides code mode. |
| 436 | + expect(cursorRequestUsesCodeMode([codeModeExec(), { name: "read_file", namespace: "mcp__fs", description: "R", parameters: {} }], { name: "read_file" })).toBe(false); |
| 437 | + }); |
| 438 | + |
| 439 | + test("teaches the nested-helper contract instead of a top-level shell bridge", () => { |
| 440 | + const note = buildCursorToolGuidanceSystemNote([codeModeExec()]); |
| 441 | + expect(note).toBeDefined(); |
| 442 | + if (!note) throw new Error("Expected Cursor tool guidance note"); |
| 443 | + |
| 444 | + expect(note).toContain("is Codex code mode"); |
| 445 | + expect(note).toContain("V8 isolate"); |
| 446 | + expect(note).toContain("await tools.<name>(...)"); |
| 447 | + expect(note).toContain("await tools.exec_command({cmd: " + "\"" + "ls" + "\"" + "})"); |
| 448 | + expect(note).toContain("text(...)"); |
| 449 | + expect(note).toContain("There is no `require`"); |
| 450 | + |
| 451 | + // The flat-catalog shell-bridge guidance must NOT appear: naming a top-level |
| 452 | + // `exec_command` in code mode sends the model after a tool that does not exist. |
| 453 | + expect(note).not.toContain("is the Codex Responses shell bridge for this turn"); |
| 454 | + expect(note).not.toContain("mcp_opencodex-responses_shell_command"); |
| 455 | + expect(note).not.toContain("For file read/search/listing, use"); |
| 456 | + }); |
| 457 | + |
| 458 | + test("keeps other visible top-level tools callable in code mode", () => { |
| 459 | + // Code mode is about how `exec` works, not a claim that the rest of the catalog is nested. |
| 460 | + // A turn can advertise freeform `exec` alongside ordinary top-level tools, and describing |
| 461 | + // those as non-top-level would make the model refuse tools it can actually call. |
| 462 | + const note = buildCursorToolGuidanceSystemNote([ |
| 463 | + codeModeExec(), |
| 464 | + { name: "mcp__fs__read_file", description: "Read a file", parameters: {} }, |
| 465 | + ]); |
| 466 | + expect(note).toBeDefined(); |
| 467 | + if (!note) throw new Error("Expected Cursor tool guidance note"); |
| 468 | + |
| 469 | + expect(note).toContain("is Codex code mode"); |
| 470 | + expect(note).toContain("remains callable at the top level as usual"); |
| 471 | + expect(note).toContain("mcp__fs__read_file"); |
| 472 | + expect(note).not.toContain("they are not separate top-level tools"); |
| 473 | + }); |
| 474 | + |
| 475 | + test("keeps flat-catalog shell-bridge guidance when a bare bridge is advertised", () => { |
| 476 | + const note = buildCursorToolGuidanceSystemNote([{ name: "exec_command", description: "Run", parameters: {} }]); |
| 477 | + expect(note).toBeDefined(); |
| 478 | + if (!note) throw new Error("Expected Cursor tool guidance note"); |
| 479 | + |
| 480 | + expect(note).toContain("is the Codex Responses shell bridge for this turn"); |
| 481 | + expect(note).not.toContain("is Codex code mode"); |
| 482 | + expect(note).not.toContain("V8 isolate"); |
| 483 | + }); |
| 484 | +}); |
0 commit comments