The Agent Loop and a Tool Framework

import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.List;
import java.util.Map;
import java.util.function.Function;

public class SmallestLoop {
    record Call(String tool, String argument) {}
    record Reply(String text, Call call) {}                     // call is null when the model answers in text

    public static void main(String[] args) {
        Deque<Reply> script = new ArrayDeque<>(List.of(
            new Reply("", new Call("read_file", "pom.xml")),
            new Reply("", new Call("count_lines", "pom.xml")),
            new Reply("pom.xml has 3 lines and names the project demo.", null)));
        Function<List<String>, Reply> model = history -> {      // a fake model: ignores the history, replays the script
            System.out.println("  model receives " + history.size() + " messages");
            return script.poll();
        };
        Map<String, String> files = Map.of("pom.xml", "<project>\n  <name>demo</name>\n</project>");
        Map<String, Function<String, String>> tools = Map.of(
            "read_file", path -> files.getOrDefault(path, "no such file: " + path),
            "count_lines", path -> String.valueOf(files.get(path).lines().count()));

        List<String> history = new ArrayList<>(List.of("user: Describe pom.xml"));
        for (int step = 1; ; step++) {
            System.out.println("step " + step);
            Reply reply = model.apply(List.copyOf(history));
            if (reply.call() == null) {                              // no tool call: the loop ends
                history.add("assistant: " + reply.text());
                break;
            }
            String result = tools.get(reply.call().tool()).apply(reply.call().argument());
            history.add("assistant: call " + reply.call().tool() + "(" + reply.call().argument() + ")");
            history.add("tool: " + result.replace("\n", "\\n"));
        }
        System.out.println("history:");
        history.forEach(m -> System.out.println("  " + m));
    }
}

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

public class MessageTypes {
    sealed interface Message permits SystemMessage, UserMessage, AssistantMessage, ToolMessage {}
    record SystemMessage(String text) implements Message {}
    record UserMessage(String text) implements Message {}
    record ToolCall(String id, String name, String arguments) {}
    record AssistantMessage(String text, List<ToolCall> toolCalls) implements Message {}
    record ToolMessage(String callId, String name, String content, boolean isError) implements Message {}

    static String describe(Message m) {
        return switch (m) {                                     // no default: the compiler checks every case
            case SystemMessage s -> "system     " + s.text();
            case UserMessage u -> "user       " + u.text();
            case AssistantMessage a when a.toolCalls().isEmpty() -> "assistant  " + a.text();
            case AssistantMessage a -> "assistant  calls " + a.toolCalls().stream().map(c -> c.id() + ":" + c.name() + c.arguments()).toList();
            case ToolMessage t -> "tool       " + t.callId() + (t.isError() ? " (error) " : " ") + t.content();
        };
    }

    /** The rules a server enforces: results answer open calls, and every call is answered before the next turn. */
    static List<String> problems(List<Message> history) {
        List<String> problems = new ArrayList<>();
        Set<String> open = new HashSet<>();
        for (int i = 0; i < history.size(); i++) {
            Message m = history.get(i);
            if (m instanceof ToolMessage t && !open.remove(t.callId())) problems.add("message " + i + ": result for unknown call " + t.callId());
            if (!(m instanceof ToolMessage) && !open.isEmpty()) problems.add("message " + i + ": calls without results " + open);
            if (!(m instanceof ToolMessage)) open.clear();
            if (m instanceof AssistantMessage a) a.toolCalls().forEach(c -> open.add(c.id()));
        }
        return problems;
    }

    public static void main(String[] args) {
        List<Message> good = List.of(
            new SystemMessage("You are a coding agent."),
            new UserMessage("Compare pom.xml and README.md"),
            new AssistantMessage("", List.of(new ToolCall("c1", "read_file", "{\"path\":\"pom.xml\"}"),
                                             new ToolCall("c2", "read_file", "{\"path\":\"README.md\"}"))),
            new ToolMessage("c1", "read_file", "<project>demo</project>", false),
            new ToolMessage("c2", "read_file", "NoSuchFileException: README.md", true),
            new AssistantMessage("pom.xml names the project demo; README.md is missing.", List.of()));
        good.forEach(m -> System.out.println(describe(m)));
        System.out.println("problems: " + problems(good));

        List<Message> broken = new ArrayList<>(good.subList(0, 4));     // the result for c2 is missing
        broken.add(new ToolMessage("c9", "read_file", "?", false));
        broken.add(new UserMessage("Go on"));
        System.out.println("problems: " + problems(broken));
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class ToolInterface {
    static final ObjectMapper JSON = new ObjectMapper();

    record ToolSpec(String name, String description, JsonNode parameters) {}

    interface Tool {
        String name();
        String description();
        JsonNode schema();                                      // JSON Schema of the arguments object
        String run(JsonNode args) throws Exception;
        default boolean readOnly() { return false; }
        default ToolSpec spec() { return new ToolSpec(name(), description(), schema()); }
    }

    static final class WordCount implements Tool {
        public String name() { return "word_count"; }
        public String description() { return "Count the words in a text."; }
        public JsonNode schema() {
            return JSON.createObjectNode().put("type", "object")
                .<com.fasterxml.jackson.databind.node.ObjectNode>set("properties", JSON.createObjectNode()
                    .set("text", JSON.createObjectNode().put("type", "string")))
                .set("required", JSON.createArrayNode().add("text"));
        }
        public String run(JsonNode args) {
            String text = args.get("text").asText().strip();
            return String.valueOf(text.isEmpty() ? 0 : text.split("\\s+").length);
        }
        @Override public boolean readOnly() { return true; }
    }

    public static void main(String[] args) throws Exception {
        Tool tool = new WordCount();
        System.out.println("spec sent to the model: " + JSON.writeValueAsString(tool.spec()));
        System.out.println("read-only: " + tool.readOnly());
        for (String arguments : new String[] {"{\"text\": \"the agent loop calls tools\"}", "{\"text\": \"   \"}"}) {
            JsonNode parsed = JSON.readTree(arguments);              // the model sends arguments as a JSON string
            System.out.println("run(" + arguments + ") = " + tool.run(parsed));
        }
    }
}

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.RecordComponent;
import java.lang.reflect.Type;
import java.util.List;

public class RecordSchemas {
    static final ObjectMapper JSON = new ObjectMapper();

    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.RECORD_COMPONENT)
    @interface Param {
        String value() default "";                              // the description the model reads
        boolean optional() default false;
    }

    enum Mode { OVERWRITE, APPEND }
    record ReadArgs(@Param("Path relative to the workspace root") String path,
                    @Param(value = "First line to return, starting at 1", optional = true) Integer offset,
                    @Param(value = "Maximum number of lines", optional = true) Integer limit) {}
    record WriteArgs(String path, String content, Mode mode) {}
    record GrepArgs(String pattern, List<String> paths, boolean ignoreCase) {}

    static ObjectNode forRecord(Class<? extends Record> type) {
        ObjectNode schema = JSON.createObjectNode().put("type", "object");
        ObjectNode properties = schema.putObject("properties");
        ArrayNode required = JSON.createArrayNode();
        for (RecordComponent c : type.getRecordComponents()) {
            ObjectNode p = forType(c.getGenericType());
            Param param = c.getAnnotation(Param.class);
            if (param != null && !param.value().isEmpty()) p.put("description", param.value());
            properties.set(c.getName(), p);
            if (param == null || !param.optional()) required.add(c.getName());
        }
        schema.set("required", required);
        schema.put("additionalProperties", false);
        return schema;
    }

    @SuppressWarnings("unchecked")
    static ObjectNode forType(Type t) {
        ObjectNode n = JSON.createObjectNode();
        if (t instanceof ParameterizedType p && p.getRawType() == List.class)
            return n.put("type", "array").set("items", forType(p.getActualTypeArguments()[0]));
        Class<?> c = (Class<?>) t;
        if (c == String.class) n.put("type", "string");
        else if (c == int.class || c == Integer.class || c == long.class || c == Long.class) n.put("type", "integer");
        else if (c == double.class || c == Double.class) n.put("type", "number");
        else if (c == boolean.class || c == Boolean.class) n.put("type", "boolean");
        else if (c.isEnum()) {
            ArrayNode values = n.put("type", "string").putArray("enum");
            for (Object k : c.getEnumConstants()) values.add(k.toString());
        } else if (c.isRecord()) return forRecord((Class<? extends Record>) c);
        else throw new IllegalArgumentException("no schema for " + c);
        return n;
    }

    public static void main(String[] args) throws Exception {
        System.out.println(JSON.writerWithDefaultPrettyPrinter().writeValueAsString(forRecord(ReadArgs.class)));
        System.out.println(JSON.writeValueAsString(forRecord(WriteArgs.class)));
        System.out.println(JSON.writeValueAsString(forRecord(GrepArgs.class)));
        ReadArgs parsed = JSON.readValue("{\"path\": \"src/Main.java\", \"limit\": 20}", ReadArgs.class);
        System.out.println("parsed: " + parsed);
    }
}

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

public class RegistryDispatch {
    static final ObjectMapper JSON = new ObjectMapper();
    record ToolCall(String id, String name, String arguments) {}
    record ToolMessage(String callId, String name, String content, boolean isError) {}

    interface Tool {
        String name();
        String run(JsonNode args) throws Exception;
    }
    record SimpleTool(String name, Map<String, String> files) implements Tool {
        public String run(JsonNode args) { return files.getOrDefault(args.path("path").asText(), "(no such file)"); }
    }

    static final class ToolRegistry {
        private final Map<String, Tool> tools = new LinkedHashMap<>();
        ToolRegistry register(Tool tool) { tools.put(tool.name(), tool); return this; }

        ToolMessage execute(ToolCall call) {
            Tool tool = tools.get(call.name());
            if (tool == null)
                return new ToolMessage(call.id(), call.name(), "unknown tool '" + call.name() + "'. Available tools: " + String.join(", ", tools.keySet()), true);
            try {
                JsonNode args = JSON.readTree(call.arguments().isBlank() ? "{}" : call.arguments());
                return new ToolMessage(call.id(), call.name(), tool.run(args), false);
            } catch (JsonProcessingException e) {
                return new ToolMessage(call.id(), call.name(), "arguments are not valid JSON: " + e.getOriginalMessage(), true);
            } catch (Exception e) {
                return new ToolMessage(call.id(), call.name(), e.getClass().getSimpleName() + ": " + e.getMessage(), true);
            }
        }
    }

    public static void main(String[] args) {
        Map<String, String> files = Map.of("pom.xml", "<project>demo</project>");
        ToolRegistry registry = new ToolRegistry()
            .register(new SimpleTool("read_file", files))
            .register(new SimpleTool("list_files", files));
        List<ToolCall> calls = List.of(
            new ToolCall("c1", "read_file", "{\"path\": \"pom.xml\"}"),
            new ToolCall("c2", "reed_file", "{\"path\": \"pom.xml\"}"),
            new ToolCall("c3", "read_file", "{\"path\": pom.xml}"),
            new ToolCall("c4", "read_file", ""));
        for (ToolCall call : calls) {
            ToolMessage r = registry.execute(call);
            System.out.println(r.callId() + (r.isError() ? " error: " : " ok:    ") + r.content());
        }
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class ArgumentValidation {
    static final ObjectMapper JSON = new ObjectMapper();

    static List<String> validate(JsonNode schema, JsonNode value) {
        List<String> errors = new ArrayList<>();
        check(schema, value, "arguments", errors);
        return errors;
    }

    static void check(JsonNode s, JsonNode v, String path, List<String> errors) {
        String type = s.path("type").asText();
        boolean ok = switch (type) {
            case "object" -> v.isObject();
            case "array" -> v.isArray();
            case "string" -> v.isTextual();
            case "integer" -> v.isIntegralNumber();
            case "number" -> v.isNumber();
            case "boolean" -> v.isBoolean();
            default -> true;
        };
        if (!ok) { errors.add(path + ": expected " + type + ", got " + kind(v)); return; }
        if (s.has("enum")) {
            boolean found = false;
            for (JsonNode e : s.get("enum")) found |= e.equals(v);
            if (!found) errors.add(path + ": must be one of " + s.get("enum"));
        }
        if (v.isObject()) {
            for (JsonNode r : s.path("required"))
                if (!v.has(r.asText())) errors.add(path + ": missing required property '" + r.asText() + "'");
            for (Map.Entry<String, JsonNode> e : v.properties()) {
                JsonNode ps = s.path("properties").get(e.getKey());
                if (ps != null) check(ps, e.getValue(), path + "." + e.getKey(), errors);
                else if (!s.path("additionalProperties").asBoolean(true)) errors.add(path + ": unknown property '" + e.getKey() + "'");
            }
        }
        if (v.isArray() && s.has("items"))
            for (int i = 0; i < v.size(); i++) check(s.get("items"), v.get(i), path + "[" + i + "]", errors);
    }

    static String kind(JsonNode v) {
        return v.isNull() ? "null" : v.isTextual() ? "string" : v.isIntegralNumber() ? "integer"
                : v.isNumber() ? "number" : v.isBoolean() ? "boolean" : v.isArray() ? "array" : "object";
    }

    public static void main(String[] args) throws Exception {
        JsonNode schema = JSON.readTree("""
            {"type": "object", "properties": {
               "path": {"type": "string"}, "limit": {"type": "integer"},
               "mode": {"type": "string", "enum": ["OVERWRITE", "APPEND"]},
               "paths": {"type": "array", "items": {"type": "string"}}},
             "required": ["path"], "additionalProperties": false}""");
        String[] attempts = {
            "{\"path\": \"pom.xml\", \"limit\": 20}",
            "{\"limit\": 20}",
            "{\"path\": \"pom.xml\", \"limit\": \"20\"}",
            "{\"path\": \"pom.xml\", \"limit\": 2.5}",
            "{\"path\": \"pom.xml\", \"mode\": \"append\"}",
            "{\"path\": \"pom.xml\", \"paths\": [\"a\", 7]}",
            "{\"file\": \"pom.xml\"}",
            "[\"pom.xml\"]"};
        for (String a : attempts) {
            List<String> errors = validate(schema, JSON.readTree(a));
            System.out.println(a);
            System.out.println("  -> " + (errors.isEmpty() ? "valid" : "invalid arguments: " + String.join("; ", errors)));
        }
    }
}

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.atomic.AtomicBoolean;

public class StopConditions {
    sealed interface Message permits UserMessage, AssistantMessage, ToolMessage {}
    record UserMessage(String text) implements Message {}
    record ToolCall(String id, String name, String arguments) {}
    record AssistantMessage(String text, List<ToolCall> toolCalls) implements Message {}
    record ToolMessage(String callId, String name, String content, boolean isError) implements Message {}
    record ModelResponse(AssistantMessage message, int promptTokens, int completionTokens) {}
    interface ModelClient { ModelResponse chat(List<Message> messages); }

    enum StopReason { COMPLETED, MAX_STEPS, MAX_TOKENS, CANCELLED }
    record AgentResult(StopReason stopReason, int steps, int tokens, boolean historyValid) {}

    static AgentResult run(ModelClient model, int maxSteps, int maxTokens, AtomicBoolean cancelled) {
        List<Message> messages = new ArrayList<>(List.of(new UserMessage("Fix the build")));
        int steps = 0, tokens = 0;
        while (true) {
            StopReason stop = cancelled.get() ? StopReason.CANCELLED
                    : steps >= maxSteps ? StopReason.MAX_STEPS
                    : tokens >= maxTokens ? StopReason.MAX_TOKENS : null;
            if (stop != null) return new AgentResult(stop, steps, tokens, messages.getLast() instanceof ToolMessage);
            ModelResponse r = model.chat(List.copyOf(messages));
            steps++;
            tokens += r.promptTokens() + r.completionTokens();
            messages.add(r.message());
            if (r.message().toolCalls().isEmpty()) return new AgentResult(StopReason.COMPLETED, steps, tokens, true);
            for (ToolCall c : r.message().toolCalls()) {
                messages.add(new ToolMessage(c.id(), c.name(), "BUILD FAILURE (line " + steps + ")", false));
                if (c.name().equals("ask_user_to_stop")) cancelled.set(true);   // stands in for Ctrl+C
            }
        }
    }

    /** A fake model that calls `tool` on every step, or answers in text on step `answerAt`. */
    static ModelClient fake(String tool, int answerAt) {
        return messages -> {
            int step = (int) messages.stream().filter(m -> m instanceof AssistantMessage).count() + 1;
            AssistantMessage reply = step == answerAt ? new AssistantMessage("The build passes.", List.of())
                    : new AssistantMessage("", List.of(new ToolCall("c" + step, tool, "{}")));
            return new ModelResponse(reply, 100 + 20 * messages.size(), 15);   // the prompt grows with the history
        };
    }

    public static void main(String[] args) {
        System.out.println(run(fake("run_build", 3), 10, 100_000, new AtomicBoolean()));
        System.out.println(run(fake("run_build", 99), 4, 100_000, new AtomicBoolean()));
        System.out.println(run(fake("run_build", 99), 50, 300, new AtomicBoolean()));
        System.out.println(run(fake("ask_user_to_stop", 99), 10, 100_000, new AtomicBoolean()));
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.NoSuchFileException;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;

public class ToolErrors {
    static final ObjectMapper JSON = new ObjectMapper();
    record ToolCall(String id, String name, String arguments) {}
    record ToolMessage(String callId, String content, boolean isError) {}

    interface Tool { String run(JsonNode args) throws Exception; }

    static ToolMessage execute(Tool tool, ToolCall call) {
        try {
            return new ToolMessage(call.id(), tool.run(JSON.readTree(call.arguments())), false);
        } catch (Exception e) {                                  // the agent keeps running; the model reads the error
            return new ToolMessage(call.id(), e.getClass().getSimpleName() + ": " + e.getMessage(), true);
        }
    }

    public static void main(String[] args) throws Exception {
        Path root = Files.createTempDirectory("ws");
        Files.createDirectories(root.resolve("src"));
        Files.writeString(root.resolve("src/Main.java"), "class Main {}\n");
        Tool read = a -> Files.readString(root.resolve(a.get("path").asText()));

        // the fake model: tries a guess, and after an error asks for the path the error suggests
        List<ToolMessage> seen = new ArrayList<>();
        List<ToolCall> plan = new ArrayList<>(List.of(new ToolCall("c1", "read_file", "{\"path\": \"Main.java\"}")));
        for (int step = 1; !plan.isEmpty(); step++) {
            ToolCall call = plan.removeFirst();
            ToolMessage result = execute(read, call);
            seen.add(result);
            System.out.println("step " + step + " " + call.arguments() + " -> " + (result.isError() ? "error " : "ok ") + result.content().strip().replace(root.toString(), "<root>"));
            if (result.isError() && result.content().startsWith("NoSuchFileException"))
                plan.add(new ToolCall("c" + (step + 1), "read_file", "{\"path\": \"src/Main.java\"}"));
        }
        ToolMessage typeError = execute(read, new ToolCall("c3", "read_file", "{}"));
        System.out.println("missing argument -> " + typeError.content());
        ToolMessage directory = execute(read, new ToolCall("c4", "read_file", "{\"path\": \"src\"}"));
        System.out.println("directory -> " + directory.content().replace(root.toString(), "<root>"));
        System.out.println("errors seen by the model: " + seen.stream().filter(ToolMessage::isError).count());
    }
}

import java.util.concurrent.Callable;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.FutureTask;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.concurrent.atomic.AtomicBoolean;

public class ToolTimeouts {
    static String runWithTimeout(String name, Callable<String> tool, long timeoutMillis) {
        FutureTask<String> task = new FutureTask<>(tool);
        Thread.ofVirtual().name("tool-" + name).start(task);
        try {
            return "ok: " + task.get(timeoutMillis, TimeUnit.MILLISECONDS);
        } catch (TimeoutException e) {
            task.cancel(true);                                   // interrupts the tool's thread
            return "error: " + name + " timed out after " + timeoutMillis + " ms";
        } catch (ExecutionException e) {
            return "error: " + e.getCause();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return "error: interrupted";
        }
    }

    public static void main(String[] args) throws Exception {
        AtomicBoolean slowSawInterrupt = new AtomicBoolean();
        AtomicBoolean stubbornFinished = new AtomicBoolean();
        Thread[] threads = new Thread[2];                       // the tool threads, to wait for them at the end

        System.out.println(runWithTimeout("fast", () -> "42", 1000));
        System.out.println(runWithTimeout("slow", () -> {
            threads[0] = Thread.currentThread();
            try { Thread.sleep(10_000); } catch (InterruptedException e) { slowSawInterrupt.set(true); throw e; }
            return "never";
        }, 1000));
        System.out.println(runWithTimeout("stubborn", () -> {
            threads[1] = Thread.currentThread();
            for (int i = 0; i < 6; i++) {
                try { Thread.sleep(300); } catch (InterruptedException ignored) { }   // swallows the interrupt
            }
            stubbornFinished.set(true);
            return "late";
        }, 1000));
        threads[0].join();
        System.out.println("slow tool saw the interrupt: " + slowSawInterrupt.get());
        threads[1].join();
        System.out.println("stubborn tool ran to the end anyway: " + stubbornFinished.get());
    }
}

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.IntStream;

public class HeadAndTail {
    /** Keeps whole lines from the head and the tail, about maxChars / 2 characters each. */
    static String truncate(String text, int maxChars) {
        if (text.length() <= maxChars) return text;
        int budget = maxChars / 2;
        String[] lines = text.split("\n", -1);
        int head = 0, used = 0;
        while (head < lines.length && used + lines[head].length() + 1 <= budget) used += lines[head++].length() + 1;
        int tail = lines.length;
        used = 0;
        while (tail > head && used + lines[tail - 1].length() + 1 <= budget) used += lines[--tail].length() + 1;
        int omitted = tail - head;
        String marker = "[... " + omitted + (omitted == 1 ? " line" : " lines") + " omitted, " + text.length() + " characters in total ...]";
        if (head == 0 && tail == lines.length)                   // one huge line: cut characters instead
            return text.substring(0, budget) + "\n" + marker + "\n" + text.substring(text.length() - budget);
        List<String> out = new ArrayList<>(Arrays.asList(lines).subList(0, head));
        out.add(marker);
        out.addAll(Arrays.asList(lines).subList(tail, lines.length));
        return String.join("\n", out);
    }

    public static void main(String[] args) {
        String buildLog = IntStream.rangeClosed(1, 200).mapToObj(i -> "[INFO] Compiling file " + i + " of 200")
            .collect(Collectors.joining("\n"))
            + "\n[ERROR] Main.java:[12,5] cannot find symbol\n[INFO] BUILD FAILURE";
        System.out.println("log: " + buildLog.length() + " characters, " + buildLog.lines().count() + " lines");
        System.out.println(truncate(buildLog, 300));
        System.out.println();
        String minified = "x".repeat(5000);
        String cut = truncate(minified, 40);
        System.out.println(cut);
        System.out.println("short text unchanged: " + truncate("BUILD SUCCESS", 300).equals("BUILD SUCCESS"));
    }
}

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;

public class ParallelCalls {
    record ToolCall(String id, String name, String path) {}
    record ToolMessage(String callId, String content) {}

    public static void main(String[] args) throws Exception {
        List<ToolCall> calls = List.of(new ToolCall("c1", "read_file", "pom.xml"),
            new ToolCall("c2", "read_file", "README.md"), new ToolCall("c3", "read_file", "src/Main.java"));
        CountDownLatch allStarted = new CountDownLatch(calls.size());
        CountDownLatch c3Done = new CountDownLatch(1);
        List<String> completionOrder = java.util.Collections.synchronizedList(new ArrayList<>());

        List<Future<ToolMessage>> futures = new ArrayList<>();
        try (ExecutorService pool = Executors.newVirtualThreadPerTaskExecutor()) {
            for (ToolCall call : calls) {
                futures.add(pool.submit(() -> {
                    allStarted.countDown();
                    boolean together = allStarted.await(10, TimeUnit.SECONDS);   // true only if all three run at once
                    if (!call.id().equals("c3")) c3Done.await();                // force c3 to finish first
                    completionOrder.add(call.id());
                    if (call.id().equals("c3")) c3Done.countDown();
                    return new ToolMessage(call.id(), "contents of " + call.path() + (together ? "" : " (ran alone)"));
                }));
            }
        }                                                            // close() waits for all tasks
        System.out.println("first to finish: " + completionOrder.getFirst());
        for (Future<ToolMessage> f : futures) {                      // results in call order, not completion order
            ToolMessage m = f.resultNow();
            System.out.println(m.callId() + " -> " + m.content());
        }
    }
}

import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;

public class SystemPrompts {
    static String build(Map<String, String> sections) {
        StringBuilder sb = new StringBuilder();
        sections.forEach((title, body) -> sb.append(title.isEmpty() ? "" : "# " + title + "\n").append(body.strip()).append("\n\n"));
        return sb.toString().strip();
    }

    public static void main(String[] args) {
        String minimal = build(Map.of("", "You are a coding agent. Use the tools to inspect and change files. "
            + "When the task is done, reply with a short summary and no tool call."));

        Map<String, String> sections = new LinkedHashMap<>();
        sections.put("", "You are loop, a coding agent working in the user's repository.");
        sections.put("Rules", """
            - Read a file before you edit it.
            - Make the smallest change that completes the task.
            - Run the tests after every change and read the failures.
            - Do not invent file contents; use read_file.
            - Stop and ask when the task is ambiguous.""");
        sections.put("Tools", """
            read_file reads a text file. write_file creates or replaces a file. edit_file replaces one exact
            string. run_command runs a shell command in the workspace and returns its exit code and output.""");
        sections.put("Output", "Reply in plain text. Keep answers under 10 lines unless the user asks for more.");
        sections.put("Environment", """
            Working directory: /work/demo
            Operating system: Linux
            Date: 2026-10-03
            Git repository: yes""");
        sections.put("Project instructions", "From AGENTS.md: build with `mvn -q package`; tests live in src/test/java.");
        String full = build(sections);

        for (var e : List.of(Map.entry("minimal", minimal), Map.entry("full", full)))
            System.out.printf(Locale.ROOT, "%-8s %4d characters, about %3d tokens%n", e.getKey(), e.getValue().length(), e.getValue().length() / 4);
        System.out.println("---");
        System.out.println(full);
    }
}

import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.concurrent.CopyOnWriteArrayList;

public class Listeners {
    record ToolCall(String id, String name, String arguments) {}
    record AssistantMessage(String text, List<ToolCall> toolCalls) {}
    record ToolMessage(String callId, String name, String content, boolean isError) {}
    enum StopReason { COMPLETED, MAX_STEPS, MAX_TOKENS, CANCELLED }
    record AgentResult(StopReason stopReason, String finalText, int steps, int tokens) {}

    interface AgentListener {
        default void onAssistant(AssistantMessage message) {}
        default void onToolCall(ToolCall call) {}
        default void onToolResult(ToolMessage result) {}
        default void onStop(AgentResult result) {}
    }

    /** What a terminal UI prints. */
    static final class ConsoleView implements AgentListener {
        public void onAssistant(AssistantMessage m) { if (!m.text().isEmpty()) System.out.println("assistant: " + m.text()); }
        public void onToolCall(ToolCall c) { System.out.println("  > " + c.name() + " " + c.arguments()); }
        public void onToolResult(ToolMessage r) {
            String first = r.content().lines().findFirst().orElse("");
            System.out.println("  < " + (r.isError() ? "error: " : "") + first + " (" + r.content().lines().count() + " lines)");
        }
        public void onStop(AgentResult r) { System.out.println("[" + r.stopReason() + " after " + r.steps() + " steps, " + r.tokens() + " tokens]"); }
    }

    /** Counts calls per tool, for a status line or a log. */
    static final class Stats implements AgentListener {
        final Map<String, Integer> calls = new TreeMap<>();
        int errors;
        public void onToolCall(ToolCall c) { calls.merge(c.name(), 1, Integer::sum); }
        public void onToolResult(ToolMessage r) { if (r.isError()) errors++; }
    }

    public static void main(String[] args) {
        List<AgentListener> listeners = new CopyOnWriteArrayList<>();
        ConsoleView view = new ConsoleView();
        Stats stats = new Stats();
        listeners.add(view);
        listeners.add(stats);

        // the events an agent run emits, in order (Example 14 emits them from the real loop)
        ToolCall c1 = new ToolCall("c1", "read_file", "{\"path\":\"Main.java\"}");
        ToolCall c2 = new ToolCall("c2", "read_file", "{\"path\":\"src/Main.java\"}");
        listeners.forEach(l -> l.onAssistant(new AssistantMessage("I will read the main class.", List.of(c1))));
        listeners.forEach(l -> l.onToolCall(c1));
        listeners.forEach(l -> l.onToolResult(new ToolMessage("c1", "read_file", "NoSuchFileException: Main.java", true)));
        listeners.forEach(l -> l.onAssistant(new AssistantMessage("", List.of(c2))));
        listeners.forEach(l -> l.onToolCall(c2));
        listeners.forEach(l -> l.onToolResult(new ToolMessage("c2", "read_file", "class Main {\n}\n", false)));
        listeners.forEach(l -> l.onAssistant(new AssistantMessage("Main is an empty class.", List.of())));
        listeners.forEach(l -> l.onStop(new AgentResult(StopReason.COMPLETED, "Main is an empty class.", 3, 412)));
        System.out.println("stats: calls=" + stats.calls + " errors=" + stats.errors);
    }
}

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.RecordComponent;
import java.lang.reflect.Type;
import java.nio.file.NoSuchFileException;
import java.time.Duration;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.Deque;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.FutureTask;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class AgentProject {
    static final ObjectMapper JSON = new ObjectMapper();

    // ---------------- Project 21: messages ----------------
    sealed interface Message permits SystemMessage, UserMessage, AssistantMessage, ToolMessage {}
    record SystemMessage(String text) implements Message {}
    record UserMessage(String text) implements Message {}
    record ToolCall(String id, String name, String arguments) {}
    record AssistantMessage(String text, List<ToolCall> toolCalls) implements Message {
        AssistantMessage {
            text = text == null ? "" : text;
            toolCalls = toolCalls == null ? List.of() : List.copyOf(toolCalls);
        }
        static AssistantMessage text(String text) { return new AssistantMessage(text, List.of()); }
        static AssistantMessage calls(ToolCall... calls) { return new AssistantMessage("", List.of(calls)); }
    }
    record ToolMessage(String callId, String name, String content, boolean isError) implements Message {}

    // ---------------- Project 21: the model side ----------------
    record ToolSpec(String name, String description, JsonNode parameters) {}
    record ModelResponse(AssistantMessage message, int promptTokens, int completionTokens) {}

    @FunctionalInterface
    interface ModelClient {
        ModelResponse chat(List<Message> messages, List<ToolSpec> tools) throws Exception;
    }

    /** Replays canned replies in order and estimates tokens as characters / 4. */
    static final class ScriptedModel implements ModelClient {
        private final Deque<AssistantMessage> replies;
        final List<List<Message>> requests = new ArrayList<>();
        ScriptedModel(AssistantMessage... replies) { this.replies = new ArrayDeque<>(List.of(replies)); }
        @Override public ModelResponse chat(List<Message> messages, List<ToolSpec> tools) {
            requests.add(List.copyOf(messages));
            AssistantMessage reply = replies.poll();
            if (reply == null) throw new IllegalStateException("script has no reply for request " + requests.size());
            int prompt = messages.stream().mapToInt(ScriptedModel::chars).sum() / 4;
            return new ModelResponse(reply, prompt, chars(reply) / 4);
        }

        static int chars(Message m) {
            return switch (m) {
                case SystemMessage s -> s.text().length();
                case UserMessage u -> u.text().length();
                case AssistantMessage a -> a.text().length()
                        + a.toolCalls().stream().mapToInt(c -> c.name().length() + c.arguments().length()).sum();
                case ToolMessage t -> t.content().length();
            };
        }
    }


    // ---------------- Project 21: tools ----------------
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.RECORD_COMPONENT)
    @interface Param {
        String value() default "";
        boolean optional() default false;
    }

    @FunctionalInterface
    interface ToolFunction<A> { String apply(A args) throws Exception; }

    interface Tool {
        String name();
        String description();
        JsonNode schema();
        String run(JsonNode args) throws Exception;
        default boolean readOnly() { return false; }
        default ToolSpec spec() { return new ToolSpec(name(), description(), schema()); }

        /** A tool whose arguments are a record; the schema comes from the record's components. */
        static <A extends Record> Tool of(String name, String description, boolean readOnly, Class<A> type, ToolFunction<A> fn) {
            JsonNode schema = Schemas.forRecord(type);
            return new Tool() {
                public String name() { return name; }
                public String description() { return description; }
                public JsonNode schema() { return schema; }
                public boolean readOnly() { return readOnly; }
                public String run(JsonNode args) throws Exception { return fn.apply(JSON.treeToValue(args, type)); }
            };
        }
    }

    static final class Schemas {
        static ObjectNode forRecord(Class<? extends Record> type) {
            ObjectNode schema = JSON.createObjectNode().put("type", "object");
            ObjectNode properties = schema.putObject("properties");
            ArrayNode required = JSON.createArrayNode();
            for (RecordComponent c : type.getRecordComponents()) {
                ObjectNode p = forType(c.getGenericType());
                Param param = c.getAnnotation(Param.class);
                if (param != null && !param.value().isEmpty()) p.put("description", param.value());
                properties.set(c.getName(), p);
                if (param == null || !param.optional()) required.add(c.getName());
            }
            schema.set("required", required);
            schema.put("additionalProperties", false);
            return schema;
        }

        @SuppressWarnings("unchecked")
        static ObjectNode forType(Type t) {
            ObjectNode n = JSON.createObjectNode();
            if (t instanceof ParameterizedType p && p.getRawType() == List.class)
                return n.put("type", "array").set("items", forType(p.getActualTypeArguments()[0]));
            Class<?> c = (Class<?>) t;
            if (c == String.class) n.put("type", "string");
            else if (c == int.class || c == Integer.class || c == long.class || c == Long.class) n.put("type", "integer");
            else if (c == double.class || c == Double.class) n.put("type", "number");
            else if (c == boolean.class || c == Boolean.class) n.put("type", "boolean");
            else if (c.isEnum()) {
                ArrayNode values = n.put("type", "string").putArray("enum");
                for (Object k : c.getEnumConstants()) values.add(k.toString());
            } else if (c.isRecord()) return forRecord((Class<? extends Record>) c);
            else throw new IllegalArgumentException("no schema for " + c);
            return n;
        }

        static List<String> validate(JsonNode schema, JsonNode value) {
            List<String> errors = new ArrayList<>();
            check(schema, value, "arguments", errors);
            return errors;
        }

        private static void check(JsonNode s, JsonNode v, String path, List<String> errors) {
            String type = s.path("type").asText();
            boolean ok = switch (type) {
                case "object" -> v.isObject();
                case "array" -> v.isArray();
                case "string" -> v.isTextual();
                case "integer" -> v.isIntegralNumber();
                case "number" -> v.isNumber();
                case "boolean" -> v.isBoolean();
                default -> true;
            };
            if (!ok) { errors.add(path + ": expected " + type + ", got " + kind(v)); return; }
            if (s.has("enum")) {
                boolean found = false;
                for (JsonNode e : s.get("enum")) found |= e.equals(v);
                if (!found) errors.add(path + ": must be one of " + s.get("enum"));
            }
            if (v.isObject()) {
                for (JsonNode r : s.path("required"))
                    if (!v.has(r.asText())) errors.add(path + ": missing required property '" + r.asText() + "'");
                for (Map.Entry<String, JsonNode> e : v.properties()) {
                    JsonNode ps = s.path("properties").get(e.getKey());
                    if (ps != null) check(ps, e.getValue(), path + "." + e.getKey(), errors);
                    else if (!s.path("additionalProperties").asBoolean(true)) errors.add(path + ": unknown property '" + e.getKey() + "'");
                }
            }
            if (v.isArray() && s.has("items"))
                for (int i = 0; i < v.size(); i++) check(s.get("items"), v.get(i), path + "[" + i + "]", errors);
        }

        static String kind(JsonNode v) {
            return v.isNull() ? "null" : v.isTextual() ? "string" : v.isIntegralNumber() ? "integer"
                    : v.isNumber() ? "number" : v.isBoolean() ? "boolean" : v.isArray() ? "array" : "object";
        }
    }

    static final class ToolRegistry {
        private final Map<String, Tool> tools = new LinkedHashMap<>();
        private final Duration timeout;
        private final int maxOutputChars;

        ToolRegistry(Duration timeout, int maxOutputChars) {
            this.timeout = timeout;
            this.maxOutputChars = maxOutputChars;
        }

        ToolRegistry register(Tool tool) { tools.put(tool.name(), tool); return this; }
        List<ToolSpec> specs() { return tools.values().stream().map(Tool::spec).toList(); }
        boolean isReadOnly(ToolCall call) { Tool t = tools.get(call.name()); return t != null && t.readOnly(); }

        /** Never throws: every problem becomes an error result that the model can read. */
        ToolMessage execute(ToolCall call) {
            Tool tool = tools.get(call.name());
            if (tool == null)
                return result(call, true, "unknown tool '" + call.name() + "'. Available tools: " + String.join(", ", tools.keySet()));
            JsonNode args;
            try {
                args = JSON.readTree(call.arguments() == null || call.arguments().isBlank() ? "{}" : call.arguments());
            } catch (JsonProcessingException e) {
                return result(call, true, "arguments are not valid JSON: " + e.getOriginalMessage());
            }
            List<String> problems = Schemas.validate(tool.schema(), args);
            if (!problems.isEmpty()) return result(call, true, "invalid arguments: " + String.join("; ", problems));
            FutureTask<String> task = new FutureTask<>(() -> tool.run(args));
            Thread.ofVirtual().name("tool-" + call.name()).start(task);
            try {
                return result(call, false, task.get(timeout.toMillis(), TimeUnit.MILLISECONDS));
            } catch (TimeoutException e) {
                task.cancel(true);
                return result(call, true, "timed out after " + timeout.toMillis() + " ms");
            } catch (ExecutionException e) {
                Throwable cause = e.getCause();
                return result(call, true, cause.getClass().getSimpleName() + ": " + cause.getMessage());
            } catch (InterruptedException e) {
                task.cancel(true);
                Thread.currentThread().interrupt();
                return result(call, true, "interrupted");
            }
        }

        private ToolMessage result(ToolCall call, boolean isError, String content) {
            return new ToolMessage(call.id(), call.name(), truncate(content == null ? "" : content, maxOutputChars), isError);
        }

        /** Keeps whole lines from the head and the tail, about maxChars / 2 characters each. */
        static String truncate(String text, int maxChars) {
            if (text.length() <= maxChars) return text;
            int budget = maxChars / 2;
            String[] lines = text.split("\n", -1);
            int head = 0, used = 0;
            while (head < lines.length && used + lines[head].length() + 1 <= budget) used += lines[head++].length() + 1;
            int tail = lines.length;
            used = 0;
            while (tail > head && used + lines[tail - 1].length() + 1 <= budget) used += lines[--tail].length() + 1;
            int omitted = tail - head;
        String marker = "[... " + omitted + (omitted == 1 ? " line" : " lines") + " omitted, " + text.length() + " characters in total ...]";
            if (head == 0 && tail == lines.length)              // one huge line: cut characters instead
                return text.substring(0, budget) + "\n" + marker + "\n" + text.substring(text.length() - budget);
            List<String> out = new ArrayList<>(Arrays.asList(lines).subList(0, head));
            out.add(marker);
            out.addAll(Arrays.asList(lines).subList(tail, lines.length));
            return String.join("\n", out);
        }
    }

    // ---------------- Project 21: the agent ----------------
    enum StopReason { COMPLETED, MAX_STEPS, MAX_TOKENS, CANCELLED }
    record AgentResult(StopReason stopReason, String finalText, int steps, int tokens) {}
    record AgentConfig(String systemPrompt, int maxSteps, int maxTokens) {}

    interface AgentListener {
        default void onAssistant(AssistantMessage message) {}
        default void onToolCall(ToolCall call) {}
        default void onToolResult(ToolMessage result) {}
        default void onStop(AgentResult result) {}
    }

    static final class Agent {
        private final ModelClient model;
        private final ToolRegistry tools;
        private final AgentConfig config;
        private final List<Message> messages = new ArrayList<>();
        private final List<AgentListener> listeners = new CopyOnWriteArrayList<>();
        private volatile boolean cancelled;

        Agent(ModelClient model, ToolRegistry tools, AgentConfig config) {
            this.model = model;
            this.tools = tools;
            this.config = config;
            messages.add(new SystemMessage(config.systemPrompt()));
        }

        Agent addListener(AgentListener listener) { listeners.add(listener); return this; }
        void cancel() { cancelled = true; }
        List<Message> messages() { return Collections.unmodifiableList(messages); }

        AgentResult run(String task) throws Exception {
            cancelled = false;
            messages.add(new UserMessage(task));
            int steps = 0, tokens = 0;
            while (true) {
                if (cancelled) return stop(StopReason.CANCELLED, "", steps, tokens);
                if (steps >= config.maxSteps()) return stop(StopReason.MAX_STEPS, "", steps, tokens);
                if (tokens >= config.maxTokens()) return stop(StopReason.MAX_TOKENS, "", steps, tokens);
                ModelResponse response = model.chat(List.copyOf(messages), tools.specs());
                steps++;
                tokens += response.promptTokens() + response.completionTokens();
                AssistantMessage reply = response.message();
                messages.add(reply);
                listeners.forEach(l -> l.onAssistant(reply));
                if (reply.toolCalls().isEmpty()) return stop(StopReason.COMPLETED, reply.text(), steps, tokens);
                for (ToolMessage result : runTools(reply.toolCalls())) messages.add(result);
            }
        }

        private List<ToolMessage> runTools(List<ToolCall> calls) {
            List<ToolMessage> results = new ArrayList<>();
            if (calls.size() > 1 && !cancelled && calls.stream().allMatch(tools::isReadOnly)) {
                calls.forEach(c -> listeners.forEach(l -> l.onToolCall(c)));
                List<Future<ToolMessage>> futures = new ArrayList<>();
                try (ExecutorService pool = Executors.newVirtualThreadPerTaskExecutor()) {
                    for (ToolCall c : calls) futures.add(pool.submit(() -> tools.execute(c)));
                }                                                   // close() waits for every call
                for (Future<ToolMessage> f : futures) results.add(f.resultNow());
                results.forEach(r -> listeners.forEach(l -> l.onToolResult(r)));
                return results;
            }
            for (ToolCall c : calls) {                              // one at a time, in order
                listeners.forEach(l -> l.onToolCall(c));
                ToolMessage r = cancelled ? new ToolMessage(c.id(), c.name(), "cancelled before it ran", true) : tools.execute(c);
                results.add(r);
                listeners.forEach(l -> l.onToolResult(r));
            }
            return results;
        }

        private AgentResult stop(StopReason reason, String text, int steps, int tokens) {
            AgentResult result = new AgentResult(reason, text, steps, tokens);
            listeners.forEach(l -> l.onStop(result));
            return result;
        }
    }
    // ---------------- end of Project 21 ----------------

    record ReadArgs(@Param("Path relative to the workspace root") String path) {}
    record SleepArgs(int millis) {}

    static int passed, failed;
    static void check(String name, boolean ok) {
        System.out.println((ok ? "PASS " : "FAIL ") + name);
        if (ok) passed++; else failed++;
    }

    static ToolRegistry registry(Duration timeout) {
        Map<String, String> files = Map.of("pom.xml", "<project>demo</project>", "README.md", "# Demo");
        return new ToolRegistry(timeout, 2000)
            .register(Tool.of("read_file", "Read a text file", true, ReadArgs.class, a -> {
                String text = files.get(a.path());
                if (text == null) throw new NoSuchFileException(a.path());
                return text;
            }))
            .register(Tool.of("sleep", "Sleep for a while", false, SleepArgs.class, a -> {
                Thread.sleep(a.millis());
                return "slept";
            }));
    }

    static ToolCall call(String id, String name, String args) { return new ToolCall(id, name, args); }
    static final AgentConfig CONFIG = new AgentConfig("You are a coding agent.", 5, 10_000);
    static final Duration FIVE_SECONDS = Duration.ofSeconds(5);

    public static void main(String[] args) throws Exception {
        // 1. a plain answer ends the run
        ScriptedModel m1 = new ScriptedModel(AssistantMessage.text("Hello."));
        AgentResult r1 = new Agent(m1, registry(FIVE_SECONDS), CONFIG).run("Say hello.");
        check("text reply completes in one step", r1.stopReason() == StopReason.COMPLETED && r1.steps() == 1 && r1.finalText().equals("Hello."));

        // 2. a tool call, then the result goes back to the model
        ScriptedModel m2 = new ScriptedModel(AssistantMessage.calls(call("c1", "read_file", "{\"path\":\"pom.xml\"}")), AssistantMessage.text("It is a demo project."));
        new Agent(m2, registry(FIVE_SECONDS), CONFIG).run("What is in pom.xml?");
        Message last = m2.requests.get(1).getLast();
        check("second request ends with the tool result", last instanceof ToolMessage t && t.callId().equals("c1") && t.content().equals("<project>demo</project>"));

        // 3. unknown tool and 4. invalid arguments are reported, not thrown
        ScriptedModel m3 = new ScriptedModel(
            AssistantMessage.calls(call("c1", "reed_file", "{\"path\":\"pom.xml\"}")),
            AssistantMessage.calls(call("c2", "read_file", "{\"file\":\"pom.xml\"}")),
            AssistantMessage.text("done"));
        Agent a3 = new Agent(m3, registry(FIVE_SECONDS), CONFIG);
        a3.run("Read pom.xml");
        List<ToolMessage> errors = a3.messages().stream().filter(m -> m instanceof ToolMessage).map(m -> (ToolMessage) m).toList();
        check("unknown tool names the available tools", errors.get(0).isError() && errors.get(0).content().contains("Available tools: read_file, sleep"));
        check("invalid arguments are explained", errors.get(1).content().equals(
            "invalid arguments: arguments: missing required property 'path'; arguments: unknown property 'file'"));

        // 5. step limit keeps the history valid
        ScriptedModel m5 = new ScriptedModel(
            AssistantMessage.calls(call("c1", "read_file", "{\"path\":\"pom.xml\"}")),
            AssistantMessage.calls(call("c2", "read_file", "{\"path\":\"pom.xml\"}")));
        Agent a5 = new Agent(m5, registry(FIVE_SECONDS), new AgentConfig("s", 2, 10_000));
        AgentResult r5 = a5.run("loop");
        check("step limit stops after 2 steps", r5.stopReason() == StopReason.MAX_STEPS && r5.steps() == 2 && a5.messages().getLast() instanceof ToolMessage);

        // 6. cancel from a listener
        ScriptedModel m6 = new ScriptedModel(AssistantMessage.calls(call("c1", "read_file", "{\"path\":\"pom.xml\"}")));
        Agent a6 = new Agent(m6, registry(FIVE_SECONDS), CONFIG);
        a6.addListener(new AgentListener() { public void onToolResult(ToolMessage r) { a6.cancel(); } });
        check("cancel stops before the next model call", a6.run("x").stopReason() == StopReason.CANCELLED && m6.requests.size() == 1);

        // 7. exceptions and 8. timeouts become error results
        ToolMessage missing = registry(FIVE_SECONDS).execute(call("c1", "read_file", "{\"path\":\"nope.txt\"}"));
        check("exception becomes an error result", missing.isError() && missing.content().equals("NoSuchFileException: nope.txt"));
        ToolMessage slow = registry(Duration.ofMillis(300)).execute(call("c2", "sleep", "{\"millis\":5000}"));
        check("timeout becomes an error result", slow.isError() && slow.content().equals("timed out after 300 ms"));

        // 9. parallel read-only calls keep the call order
        ScriptedModel m9 = new ScriptedModel(AssistantMessage.calls(call("a", "read_file", "{\"path\":\"README.md\"}"),
            call("b", "read_file", "{\"path\":\"pom.xml\"}")), AssistantMessage.text("ok"));
        Agent a9 = new Agent(m9, registry(FIVE_SECONDS), CONFIG);
        a9.run("both");
        List<String> ids = a9.messages().stream().filter(m -> m instanceof ToolMessage).map(m -> ((ToolMessage) m).callId()).toList();
        check("results follow the call order", ids.equals(List.of("a", "b")));

        // 10. truncation keeps head and tail
        String big = String.join("\n", java.util.stream.IntStream.rangeClosed(1, 100).mapToObj(i -> "line " + i).toList());
        String cut = ToolRegistry.truncate(big, 60);
        check("truncation keeps first and last lines", cut.startsWith("line 1\n") && cut.endsWith("line 100") && cut.contains("lines omitted"));
        System.out.println(passed + " passed, " + failed + " failed");
    }
}