Add **Shared ScheduledExecutorService** for timeouts

[edburns]

Before the change?

• CopilotSession.sendAndWait() created a new ScheduledExecutorService per call, spawning a new OS thread (~1 MB stack) for every timeout, and never cancelling it on close() — leaving stale timeouts able to fire after the session was closed.
• Test Javadoc referenced "current buggy behavior" and "Without a fix" language, which becomes misleading once the fix is merged.
• ZeroTimeoutContractTest created a CopilotSession without closing it, leaking the executor's thread across tests.

After the change?

CopilotSession.java

• Added ScheduledExecutorService import.
• New field timeoutScheduler: shared single-thread scheduler, daemon thread named sendAndWait-timeout.
• Initialized in 3-arg constructor.
• sendAndWait(): replaced per-call Executors.newSingleThreadScheduledExecutor() with timeoutScheduler.schedule(). Cleanup calls timeoutTask.cancel(false) instead of scheduler.shutdown().
• close(): added timeoutScheduler.shutdownNow() before the blocking session.destroy RPC call so stale timeouts cannot fire after close.

TimeoutEdgeCaseTest.java (new)

• testTimeoutDoesNotFireAfterSessionClose: regression assertion that close() cancels pending timeouts (future not completed by stale TimeoutException).
• testSendAndWaitReusesTimeoutThread: regression assertion that two sendAndWait calls share one scheduler thread instead of spawning two.
• Uses reflection to construct a hanging JsonRpcClient (blocking InputStream, sink OutputStream).
• Class and method Javadoc rewritten as behavioral contracts rather than descriptions of pre-fix behavior.

ZeroTimeoutContractTest.java (new)

• Verifies the documented contract that timeoutMs <= 0 means "no timeout".
• Uses try-with-resources so the session (and its ScheduledExecutorService) is always closed after the test.
• Stubs session.destroy to return CompletableFuture.completedFuture(null) so close() is non-blocking; all other invoke() calls return a pending future.

SchedulerShutdownRaceTest.java (new)

• Regression coverage for the race between sendAndWait() and close(): asserts that if the scheduler is shut down between ensureNotTerminated() and schedule(), sendAndWait() returns a future that completes exceptionally with RejectedExecutionException rather than throwing directly.
• Javadoc rewritten as an invariant/contract assertion rather than a description of pre-fix failure mode.

pom.xml

• Added Mockito (mockito-core) as a test-scoped dependency to support the new Mockito-based unit tests.

Pull request checklist

• Tests for the changes have been added (for bug fixes / features)
• Docs have been reviewed and added / updated if needed (for bug fixes / features)
• mvn spotless:apply has been run to format the code
• mvn clean verify passes locally

Does this introduce a breaking change?

• Yes
• No

---

[brunoborges]

@edburns did this branch build successfully on your local machine?

[Copilot]

Pull request overview

Adds a session-level timeout scheduler to CopilotSession#sendAndWait(...) to avoid per-call thread creation and to prevent stale timeout tasks from firing after close(), with new tests covering timeout/threading edge cases.

Changes:

• Introduce a shared ScheduledExecutorService in CopilotSession for sendAndWait timeouts, canceling scheduled tasks on completion and shutting down the scheduler during close().
• Add new tests to validate timeout behavior after close(), scheduler reuse, zero-timeout semantics, and the shutdown/scheduling race.
• Add Mockito as a test dependency to support the new unit tests.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/main/java/com/github/copilot/sdk/CopilotSession.java	Replaces per-call timeout executors with a session-owned scheduler and adds shutdown behavior in close().
src/test/java/com/github/copilot/sdk/TimeoutEdgeCaseTest.java	Adds regression tests for stale timeouts after close and scheduler thread reuse.
src/test/java/com/github/copilot/sdk/ZeroTimeoutContractTest.java	Adds a contract test for timeoutMs <= 0 meaning “no timeout”.
src/test/java/com/github/copilot/sdk/SchedulerShutdownRaceTest.java	Adds a regression test for close()/sendAndWait() scheduling race handling.
pom.xml	Adds mockito-core as a test-scoped dependency.

Comments suppressed due to low confidence (2)

src/test/java/com/github/copilot/sdk/TimeoutEdgeCaseTest.java:90

• This test will deterministically spend ~5 seconds in CopilotSession.close() because the constructed JsonRpcClient never completes the session.destroy RPC and close() waits up to 5s. That makes the unit test suite significantly slower; consider using a mocked JsonRpcClient (or stubbing session.destroy to complete after a short delay) so the same behavior is exercised without a fixed multi-second stall.

                // close() blocks up to 5s on session.destroy RPC. The 2s timeout
                // fires during that window with the current per-call scheduler.
                session.close();

                assertFalse(result.isDone(), "Future should not be completed by a timeout after session is closed. "
                        + "The per-call ScheduledExecutorService leaked a TimeoutException.");
            }

src/test/java/com/github/copilot/sdk/SchedulerShutdownRaceTest.java:56

• The test creates a CopilotSession but does not close it. Even though the scheduler is manually shut down, the session still retains handlers/state; consider closing it via try-with-resources and stubbing session.destroy on the mocked JsonRpcClient to return a completed future so close() doesn't block for 5 seconds.

        var session = ctor.newInstance("race-test", mockRpc, null);

        // Shut down the scheduler without setting isTerminated,
        // simulating the race window between ensureNotTerminated() and schedule()
        var schedulerField = CopilotSession.class.getDeclaredField("timeoutScheduler");
        schedulerField.setAccessible(true);
        var scheduler = (ScheduledExecutorService) schedulerField.get(session);
        scheduler.shutdownNow();

        // With the fix: sendAndWait returns a future that completes exceptionally.
        // Without the fix: sendAndWait throws RejectedExecutionException directly.
        CompletableFuture<?> result = session.sendAndWait(new MessageOptions().setPrompt("test"), 5000);

[edburns]

@brunoborges wrote:

did this branch build successfully on your local machine?

Yes:

Full suite: 472 tests, 0 failures