// 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);
}