feat(tool-registry): rename issues→results, remove system param, timeout docs

- Rename AgenticSession.issues → results, getIssues() → getResults(),
  addIssue() → addResult(); rename SessionCheckpoint JSON key 'issues' → 'results'
- Remove unused system parameter from AgenticSession.runToolLoop and
  ToolRegistry.runToolLoop
- Add ScheduleToCloseTimeout guidance to README
- Update all test call sites

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: lex00

temporal-tool-registry/README.md

@@ -60,7 +60,7 @@ public List<String> analyze(String prompt) throws Exception {
     Provider provider = new AnthropicProvider(cfg, registry,
         "You are a code reviewer. Call flag_issue for each problem you find.");
 
-    ToolRegistry.runToolLoop(provider, registry, "" /* system prompt: "" defers to provider default */, prompt);
+    ToolRegistry.runToolLoop(provider, registry, prompt);
     return issues;
 }
 ```
@@ -97,23 +97,23 @@ For multi-turn LLM conversations that must survive activity retries, use
 ```java
 @ActivityMethod
 public List<Object> longAnalysis(String prompt) throws Exception {
-    List<Object> issues = new ArrayList<>();
+    List<Object> results = new ArrayList<>();
 
     AgenticSession.runWithSession(session -> {
         ToolRegistry registry = new ToolRegistry();
         registry.register(
             ToolDefinition.builder().name("flag").description("...").inputSchema(Map.of("type", "object")).build(),
-            input -> { session.addIssue(input); return "ok"; /* sent back to LLM */ });
+            input -> { session.addResult(input); return "ok"; /* sent back to LLM */ });
 
         AnthropicConfig cfg = AnthropicConfig.builder()
             .apiKey(System.getenv("ANTHROPIC_API_KEY")).build();
         Provider provider = new AnthropicProvider(cfg, registry, "your system prompt");
 
-        session.runToolLoop(provider, registry, "your system prompt", prompt);
-        issues.addAll(session.getIssues()); // capture after loop completes
+        session.runToolLoop(provider, registry, prompt);
+        results.addAll(session.getResults()); // capture after loop completes
     });
 
-    return issues;
+    return results;
 }
 ```
 
@@ -135,7 +135,7 @@ public void testAnalyze() throws Exception {
         MockResponse.done("analysis complete"));
 
     List<Map<String, Object>> msgs =
-        ToolRegistry.runToolLoop(provider, registry, "sys", "analyze");
+        ToolRegistry.runToolLoop(provider, registry, "analyze");
     assertTrue(msgs.size() > 2);
 }
 ```
@@ -156,7 +156,7 @@ incur billing — expect a few cents per full test run.
 
 ## Storing application results
 
-`session.getIssues()` accumulates application-level
+`session.getResults()` accumulates application-level
 results during the tool loop. Elements are serialized to JSON inside each heartbeat
 checkpoint — they must be plain maps/dicts with JSON-serializable values. A non-serializable
 value raises a non-retryable `ApplicationError` at heartbeat time rather than silently
@@ -167,17 +167,17 @@ losing data on the next retry.
 Convert your domain type to a plain dict at the tool-call site and back after the session:
 
 ```java
-record Issue(String type, String file) {}
+record Result(String type, String file) {}
 
 // Inside tool handler:
-session.addIssue(Map.of("type", "smell", "file", "Foo.java"));
+session.addResult(Map.of("type", "smell", "file", "Foo.java"));
 
 // After session (using Jackson for convenient mapping):
 // requires jackson-databind in your build.gradle:
 // implementation 'com.fasterxml.jackson.core:jackson-databind:VERSION'
 ObjectMapper mapper = new ObjectMapper();
-List<Issue> issues = session.getIssues().stream()
-    .map(m -> mapper.convertValue(m, Issue.class))
+List<Result> results = session.getResults().stream()
+    .map(m -> mapper.convertValue(m, Result.class))
     .toList();
 ```
 
@@ -203,6 +203,21 @@ Recommended timeouts:
 | Standard (Claude 3.x, GPT-4o) | 30 s |
 | Reasoning (o1, o3, extended thinking) | 300 s |
 
+### Activity-level timeout
+
+Set `setScheduleToCloseTimeout` on the activity stub options to bound the entire conversation:
+
+```java
+ActivityOptions opts = ActivityOptions.newBuilder()
+    .setScheduleToCloseTimeout(Duration.ofMinutes(10))
+    .build();
+MyActivities stub = Workflow.newActivityStub(MyActivities.class, opts);
+```
+
+The per-turn client timeout and `ScheduleToCloseTimeout` are complementary:
+- Per-turn timeout fires if one LLM call hangs (protects against a single stuck turn)
+- `ScheduleToCloseTimeout` bounds the entire conversation including all retries (protects against runaway multi-turn loops)
+
 ## MCP integration
 
 `ToolRegistry.fromMcpTools` converts a list of `McpTool` descriptors into a populated

temporal-tool-registry/src/main/java/io/temporal/toolregistry/AgenticSession.java

@@ -13,15 +13,15 @@
 import org.slf4j.LoggerFactory;
 
 /**
- * Maintains conversation state (messages and issues) across multiple turns of a tool-calling loop,
- * with heartbeat checkpointing for crash recovery.
+ * Maintains conversation state (messages and results) across multiple turns of a tool-calling
+ * loop, with heartbeat checkpointing for crash recovery.
  *
  * <p>Use {@link #runWithSession(SessionFn)} inside a Temporal activity to get automatic checkpoint
  * restore-on-retry and heartbeat on each turn:
  *
  * <pre>{@code
  * AgenticSession.runWithSession(session -> {
- *     session.runToolLoop(provider, registry, systemPrompt, userPrompt);
+ *     session.runToolLoop(provider, registry, userPrompt);
  * });
  * }</pre>
  *
@@ -32,7 +32,7 @@ public class AgenticSession {
   private static final Logger log = LoggerFactory.getLogger(AgenticSession.class);
 
   private final List<Map<String, Object>> messages = new ArrayList<>();
-  private final List<Map<String, Object>> issues = new ArrayList<>();
+  private final List<Map<String, Object>> results = new ArrayList<>();
 
   /** Creates an empty session. */
   public AgenticSession() {}
@@ -50,13 +50,12 @@ public AgenticSession() {}
    *
    * @param provider the LLM provider adapter
    * @param registry the tool registry
-   * @param system the system prompt
    * @param prompt the initial user prompt (ignored if restoring from a checkpoint that already has
    *     messages)
    * @throws ActivityCompletionException if the activity is cancelled
    * @throws Exception on API or dispatch errors
    */
-  public void runToolLoop(Provider provider, ToolRegistry registry, String system, String prompt)
+  public void runToolLoop(Provider provider, ToolRegistry registry, String prompt)
       throws Exception {
     if (messages.isEmpty()) {
       Map<String, Object> userMsg = new java.util.LinkedHashMap<>();
@@ -83,24 +82,24 @@ public void runToolLoop(Provider provider, ToolRegistry registry, String system,
    *
    * <p>Throws {@link ActivityCompletionException} if the activity has been cancelled.
    *
-   * @throws ApplicationFailure (non-retryable) if any issue is not JSON-serializable
+   * @throws ApplicationFailure (non-retryable) if any result is not JSON-serializable
    */
   public void checkpoint() throws ActivityCompletionException {
     ObjectMapper mapper = new ObjectMapper();
-    for (int i = 0; i < issues.size(); i++) {
+    for (int i = 0; i < results.size(); i++) {
       try {
-        mapper.writeValueAsString(issues.get(i));
+        mapper.writeValueAsString(results.get(i));
       } catch (Exception e) {
         throw ApplicationFailure.newNonRetryableFailure(
-            "AgenticSession: issues["
+            "AgenticSession: results["
                 + i
                 + "] is not JSON-serializable: "
                 + e.getMessage()
                 + ". Store only Map<String, Object> with JSON-serializable values.",
             "InvalidArgument");
       }
     }
-    SessionCheckpoint cp = new SessionCheckpoint(messages, issues);
+    SessionCheckpoint cp = new SessionCheckpoint(messages, results);
     Activity.getExecutionContext().heartbeat(cp);
   }
 
@@ -114,7 +113,7 @@ public void checkpoint() throws ActivityCompletionException {
    *
    * <pre>{@code
    * AgenticSession.runWithSession(session -> {
-   *     session.runToolLoop(provider, registry, systemPrompt, userPrompt);
+   *     session.runToolLoop(provider, registry, userPrompt);
    * });
    * }</pre>
    *
@@ -152,21 +151,21 @@ public List<Map<String, Object>> getMessages() {
     return Collections.unmodifiableList(messages);
   }
 
-  /** Returns an unmodifiable view of the issues collected during the session. */
-  public List<Map<String, Object>> getIssues() {
-    return Collections.unmodifiableList(issues);
+  /** Returns an unmodifiable view of the results collected during the session. */
+  public List<Map<String, Object>> getResults() {
+    return Collections.unmodifiableList(results);
   }
 
-  /** Appends an issue to the issue list. */
-  public void addIssue(Map<String, Object> issue) {
-    issues.add(issue);
+  /** Appends a result to the results list. */
+  public void addResult(Map<String, Object> result) {
+    results.add(result);
   }
 
   /** Restores session state from a checkpoint. Called by {@link #runWithSession} on retry. */
   void restore(SessionCheckpoint checkpoint) {
     messages.clear();
     messages.addAll(checkpoint.messages);
-    issues.clear();
-    issues.addAll(checkpoint.issues);
+    results.clear();
+    results.addAll(checkpoint.results);
   }
 }

temporal-tool-registry/src/main/java/io/temporal/toolregistry/SessionCheckpoint.java

@@ -15,13 +15,13 @@ class SessionCheckpoint {
   public int version = 1;
 
   public List<Map<String, Object>> messages = new ArrayList<>();
-  public List<Map<String, Object>> issues = new ArrayList<>();
+  public List<Map<String, Object>> results = new ArrayList<>();
 
   /** No-arg constructor required for Jackson deserialization. */
   SessionCheckpoint() {}
 
-  SessionCheckpoint(List<Map<String, Object>> messages, List<Map<String, Object>> issues) {
+  SessionCheckpoint(List<Map<String, Object>> messages, List<Map<String, Object>> results) {
     this.messages = new ArrayList<>(messages);
-    this.issues = new ArrayList<>(issues);
+    this.results = new ArrayList<>(results);
   }
 }

temporal-tool-registry/src/main/java/io/temporal/toolregistry/ToolRegistry.java

@@ -139,12 +139,11 @@ public List<Map<String, Object>> toOpenAI() {
    *
    * @param provider the LLM provider adapter
    * @param registry the tool registry (may be the same object, provided for clarity)
-   * @param system the system prompt
    * @param prompt the initial user prompt
    * @return the full message history on completion
    */
   public static List<Map<String, Object>> runToolLoop(
-      Provider provider, ToolRegistry registry, String system, String prompt) throws Exception {
+      Provider provider, ToolRegistry registry, String prompt) throws Exception {
     List<Map<String, Object>> messages = new ArrayList<>();
     Map<String, Object> userMsg = new LinkedHashMap<>();
     userMsg.put("role", "user");

temporal-tool-registry/src/test/java/io/temporal/toolregistry/ToolRegistryTest.java

@@ -148,7 +148,7 @@ public void testRunToolLoop_singleDone() throws Exception {
         new io.temporal.toolregistry.testing.MockProvider(
             io.temporal.toolregistry.testing.MockResponse.done("finished"));
 
-    List<Map<String, Object>> msgs = ToolRegistry.runToolLoop(provider, registry, "sys", "hello");
+    List<Map<String, Object>> msgs = ToolRegistry.runToolLoop(provider, registry, "hello");
 
     // user + assistant
     assertEquals(2, msgs.size());
@@ -195,7 +195,7 @@ public void testRunToolLoop_withToolCall() throws Exception {
           }
         });
 
-    List<Map<String, Object>> msgs = ToolRegistry.runToolLoop(provider, registry, "sys", "go");
+    List<Map<String, Object>> msgs = ToolRegistry.runToolLoop(provider, registry, "go");
 
     assertEquals(Arrays.asList("first", "second"), collected);
     // user + (assistant + tool_result_wrapper)*2 + final assistant
@@ -335,7 +335,7 @@ public void testIntegration_Anthropic() throws Exception {
             "You must call record() exactly once with value='hello'.");
 
     ToolRegistry.runToolLoop(
-        provider, registry, "", "Please call the record tool with value='hello'.");
+        provider, registry, "Please call the record tool with value='hello'.");
 
     assertTrue("expected 'hello' in collected", collected.contains("hello"));
   }
@@ -355,7 +355,7 @@ public void testIntegration_OpenAI() throws Exception {
             "You must call record() exactly once with value='hello'.");
 
     ToolRegistry.runToolLoop(
-        provider, registry, "", "Please call the record tool with value='hello'.");
+        provider, registry, "Please call the record tool with value='hello'.");
 
     assertTrue("expected 'hello' in collected", collected.contains("hello"));
   }