// Copyright 2026 TesterArmy. // Modified by Dario Kondratiuk. // SPDX-License-Identifier: Apache-2.0 using System.Text.Json; using System.Text.RegularExpressions; using E2E.Internal; namespace E2E; /// One turn of the agent model. Tool calls are executed by the agent, never by the model itself. public interface IAgentModel { /// Provider and model id, printed in the run summary. Changing it does not miss the replay cache. string Name { get; } Task CompleteAsync(ModelRequest request, CancellationToken cancellationToken); } public sealed class ModelRequest { public required string System { get; init; } public required IReadOnlyList Messages { get; init; } public required IReadOnlyList Tools { get; init; } /// /// The agent's provider options, keyed by provider, for the model to pass on. Null when none are set. /// adds the entry under its provider name to the request body. /// public IReadOnlyDictionary? ProviderOptions { get; init; } /// /// Upstream's ProviderHints.markLatest, which only the act tool loop calls: the next turn repeats everything up /// to the newest message, so marks that message for caching. Judgments and extractions leave it off. /// public bool MarkLatest { get; init; } /// /// Upstream's ModelCall.schema: a closed response grammar the provider is asked to fill as structured output. When it is /// set, is empty and the model answers with one JSON object that matches it, as ; /// the agent validates that text itself. Null for a turn that offers tools. A custom must handle it. /// public JsonElement? Schema { get; init; } /// Upstream's ModelCall.schemaName: the name sent with , for the providers that name a structured output. public string? SchemaName { get; init; } /// Upstream's ModelCall.maxRetries: provider transport retries for this call. Null keeps . public int? MaxRetries { get; init; } /// /// Upstream's ModelCall.toolChoice (the AI SDK's toolChoice): how the model must use the tools it is offered. Null leaves /// the choice to the provider, which is . The act tool loop asks for /// and names done on its forced-conclusion turns. A custom that cannot force a tool may ignore it. /// public ModelToolChoice? ToolChoice { get; init; } /// Redacts the secrets of the step from a provider failure that quotes the response body. internal Redactor Redactor { get; init; } = Redactor.None; } public sealed class ModelMessage { public required string Role { get; init; } public string? Content { get; init; } /// /// Upstream's error-text tool output: the call failed before its text was read (the SDK refused it, or the tool threw), so the /// failure streak counts it whatever the text says. Read by the loop's guards only; no provider receives it. /// internal bool ErrorText { get; init; } public IReadOnlyList? ToolCalls { get; init; } public string? ToolCallId { get; init; } public string? Name { get; init; } /// The reasoning the model returned with this turn, sent back as it came: encrypted items for , signed thinking blocks for , thought parts for , the reasoningContent blocks for , the reasoning text as a JSON string for . public IReadOnlyList? ReasoningItems { get; init; } /// The images that go with a user turn, after its text. A provider sends them as the turn's image parts; on any other role they are not sent. public IReadOnlyList? Images { get; init; } } /// An image a model reads: the encoded bytes of a screenshot, already sized for the model. /// The encoded image. /// The media type of , such as image/png. /// Width in image pixels. /// Height in image pixels. public sealed record ModelImage(byte[] Data, string MediaType, int Width, int Height); /// /// The AI SDK's ToolChoice: auto lets the model answer in prose or call any offered tool, required makes it call some /// tool, and a named tool makes it call that one. Each provider sends its own form of it (Anthropic's any, Bedrock's any, /// OpenAI's required, Gemini's ANY). /// public sealed record ModelToolChoice { private ModelToolChoice(string type, string? toolName = null) { Type = type; ToolName = toolName; } /// The model decides whether to call a tool (auto). public static ModelToolChoice Auto { get; } = new("auto"); /// The model must call some tool (required). public static ModelToolChoice Required { get; } = new("required"); /// The model must call the tool named (the SDK's { type: 'tool', toolName }). public static ModelToolChoice Tool(string toolName) { ArgumentException.ThrowIfNullOrWhiteSpace(toolName); return new("tool", toolName); } /// auto, required, or tool. public string Type { get; } /// The tool a tool choice names. Null for the other two. public string? ToolName { get; } /// Whether the choice makes the model call a tool (anything but auto). public bool Forced => Type != "auto"; } /// /// One of upstream's call warnings (CallWarning): the provider changed the request instead of failing it. A provider that sends /// auto in place of the forced tool choice it was asked for says so with Type unsupported and Feature toolChoice. /// /// The kind of warning, such as unsupported. /// The request feature it is about, such as toolChoice. /// What the provider did about it. Provider text: redact it before it reaches a message. public sealed record ModelWarning(string Type, string? Feature = null, string? Details = null); public sealed class ModelTool { public required string Name { get; init; } public required string Description { get; init; } public required JsonElement Parameters { get; init; } } public sealed class ModelToolCall { public required string Id { get; init; } public required string Name { get; init; } public required JsonElement Arguments { get; init; } /// /// What the provider attached to the call, keyed by provider (such as google: { "thoughtSignature": "..." }), which the /// call carries back on the next turn (upstream's providerMetadata of a tool call part). null when it attached none. /// public IReadOnlyDictionary? ProviderMetadata { get; init; } } public sealed class ModelCallUsage { public int InputTokens { get; init; } public int OutputTokens { get; init; } /// Input tokens the provider served from its prompt cache, when it reports the split. A part of . public int? CacheReadTokens { get; init; } /// Input tokens the provider wrote to its prompt cache, when it reports the split. A part of . public int? CacheWriteTokens { get; init; } /// The billed cost of the call in US dollars, when the provider reports one. public double? EstimatedCostUsd { get; init; } } public sealed class ModelResponse { public string? Content { get; init; } public IReadOnlyList ToolCalls { get; init; } = []; public ModelCallUsage? Usage { get; init; } /// The reasoning of the turn that the model can take back, to replay on the next turn. Empty when the model gave none. public IReadOnlyList ReasoningItems { get; init; } = []; /// /// The reasoning text of the turn (upstream's StepResult.reasoningText), null when the model gave none. Provider text: the /// step's model event carries it only after the redactor and a 600-character bound. /// public string? ReasoningText { get; init; } /// /// What the provider attached to the whole turn, keyed by provider (such as gateway: { "cost": "0.0001" }), as upstream's /// StepResult.providerMetadata. The step's trace carries it as providerMetadata of the step end, redacted. null when the /// provider attached none. /// public IReadOnlyDictionary? ProviderMetadata { get; init; } /// Upstream's call warnings (StepResult.warnings): what the provider changed in the request without failing it. Empty when it changed nothing. public IReadOnlyList Warnings { get; init; } = []; /// The AI SDK finish reason that matters to the agent: when the provider stopped the turn because it refused the request, or when it ended on an error. Null for any other turn. public string? FinishReason { get; init; } /// The provider's own word for the stop, such as refusal, when it sent one. Provider text: redact it before it reaches a message. public string? RawFinishReason { get; init; } /// The finish reason of a turn the provider refused (upstream's content-filter). public const string ContentFilter = "content-filter"; /// The finish reason of a turn the provider ended on an error (upstream's error), whatever text came with it. No built-in provider reports it; a custom may. public const string ErrorFinish = "error"; } /// Builds the tool calls a (or a test) returns. public static class ModelResponses { public static ModelResponse Done(string status, string summary, string? code = null) { return Call(VerdictTool.Name, code is null ? new { status, summary } : (object)new { status, summary, code }); } /// /// A judge's answer: one agent-judgment-2 object as the content of the turn. is /// holds, fails, or inconclusive. /// public static ModelResponse Judgment(string verdict, string explanation) { return new ModelResponse { Content = JsonSerializer.Serialize(new { protocolVersion = "agent-judgment-2", explanation, verdict }, JsonDefaults.Options), }; } public static ModelResponse Tap(string role, string name) { return Call("tap", new { role, name }); } public static ModelResponse Fill(string role, string name, string value) { return Call("type", new { role, name, value }); } public static ModelResponse Call(string name, object arguments) { ArgumentException.ThrowIfNullOrWhiteSpace(name); ArgumentNullException.ThrowIfNull(arguments); return new ModelResponse { ToolCalls = [ new ModelToolCall { Id = "call_" + name, Name = name, Arguments = JsonSerializer.SerializeToElement(arguments, JsonDefaults.Options), }, ], }; } } /// /// Returns whatever the callback decides for each request. Records every request. A callback that serves both the act loop /// and the judge may answer a judgment (a request with a ) with : /// passed reads as holds, a failed without the code ASSERTION_INCONCLUSIVE as fails, and a /// blocked or inconclusive one as inconclusive. answers it directly. A tool call that names its node by /// role and name (or testId) reaches the agent as a target id, the one the screens in the request list for it. /// public sealed partial class ScriptedModel : IAgentModel { private readonly Func _next; public ScriptedModel(Func next) { ArgumentNullException.ThrowIfNull(next); _next = next; } public string Name => "scripted"; public int CallCount { get; private set; } public List Requests { get; } = []; public Task CompleteAsync(ModelRequest request, CancellationToken cancellationToken) { cancellationToken.ThrowIfCancellationRequested(); CallCount++; Requests.Add(request); var response = Targeted(request, _next(request)); return Task.FromResult(request.Schema is null ? response : AsJudgment(response)); } // A scripted call may name a node by role and name (or test id), as a person reads the screen; the tools take the node id alone, so the // call is rewritten to the id the screens in this request list for it. A node no screen lists becomes an id that matches nothing. private static ModelResponse Targeted(ModelRequest request, ModelResponse response) { if (response.ToolCalls.Count == 0 || !response.ToolCalls.Any(call => call.Arguments.ValueKind == JsonValueKind.Object && NamesNode(call.Arguments))) { return response; } var calls = response.ToolCalls.Select(call => call.Arguments.ValueKind == JsonValueKind.Object && NamesNode(call.Arguments) ? new ModelToolCall { Id = call.Id, Name = call.Name, Arguments = Retarget(request, call.Arguments), ProviderMetadata = call.ProviderMetadata } : call).ToList(); return new ModelResponse { Content = response.Content, ToolCalls = calls, Usage = response.Usage, ReasoningText = response.ReasoningText, ProviderMetadata = response.ProviderMetadata }; } private static bool NamesNode(JsonElement arguments) => !arguments.TryGetProperty("target", out _) && (arguments.TryGetProperty("role", out _) || arguments.TryGetProperty("name", out _) || arguments.TryGetProperty("testId", out _)); private static JsonElement Retarget(ModelRequest request, JsonElement arguments) { var role = Args.String(arguments, "role"); var name = Args.String(arguments, "name"); var testId = Args.String(arguments, "testId"); var id = "missing"; foreach (var line in request.Messages.Where(message => message.Content is not null).SelectMany(message => message.Content!.Split('\n'))) { var match = ListedNode().Match(line); if (!match.Success) { continue; } if (testId is not null ? match.Groups["testid"].Value == testId : (role is null || match.Groups["role"].Value == role) && (name is null || match.Groups["name"].Value == name)) { id = match.Groups["id"].Value; } } var rewritten = new System.Text.Json.Nodes.JsonObject { ["target"] = id }; foreach (var property in arguments.EnumerateObject().Where(property => property.Name is not ("role" or "name" or "testId"))) { rewritten[property.Name] = System.Text.Json.Nodes.JsonNode.Parse(property.Value.GetRawText()); } return JsonSerializer.SerializeToElement(rewritten); } [GeneratedRegex(@"^\s*(?:added |changed )?#(?[A-Za-z0-9_-]+) (?[^\s""]+)(?: ""(?[^""]*)"")?(?:.*? testid=""(?[^""]*)"")?", RegexOptions.CultureInvariant)] private static partial Regex ListedNode(); private static ModelResponse AsJudgment(ModelResponse response) { var done = response.ToolCalls.FirstOrDefault(call => string.Equals(call.Name, VerdictTool.Name, StringComparison.Ordinal)); if (done is null || response.Content is not null) { return response; } var status = Args.String(done.Arguments, "status"); var code = Args.String(done.Arguments, "code"); var verdict = status switch { "passed" => "holds", "failed" when code != "ASSERTION_INCONCLUSIVE" => "fails", _ => "inconclusive", }; return new ModelResponse { Content = ModelResponses.Judgment(verdict, Args.String(done.Arguments, "summary") ?? "").Content, Usage = response.Usage, ReasoningText = response.ReasoningText, ProviderMetadata = response.ProviderMetadata }; } } /// The input bounds of upstream's agent/model/adapter.ts, which the observation budget and the judgment pre-flight share. internal static class ModelAdapter { /// Side of the square patch tile-based vision encoders consume an image in. private const int ImageTilePx = 28; /// /// Conservative token upper bound. UTF-8 byte length bounds every byte-level tokenizer from above, so it is used when a provider /// reports no usage and for the pre-flight ceiling. Every budget that mixes with this one (reserves, ledger size, observation size) /// is therefore in the same byte-scaled units, not in real tokens. /// public static int TokenUpperBound(string text) => System.Text.Encoding.UTF8.GetByteCount(text); /// /// Conservative token bound for one image: vision providers bill images by fixed-size patches rather than bytes, so the count of /// patches covering the image bounds every such encoder from above. /// public static int ImageTokenUpperBound(int width, int height) => (int)Math.Ceiling(Math.Max(1, width) / (double)ImageTilePx) * (int)Math.Ceiling(Math.Max(1, height) / (double)ImageTilePx); }