iTool.MyScriptRuntimes.AgentSurface 4.0.0

iTool.MyScriptRuntimes.AgentSurface

The agent-facing surface of the neutral iTool Runtime. It is not an agent: it holds no loop, no session, no model call and no persistence. Its job is to answer three questions for whatever agent runs on top, and to stay out of the Runtime SDK's way while doing it.

What it provides

The transport is the host's, not ours

StandardRuntimeAgentToolInvoker does the neutral work and stops at one seam:

public interface IAgentToolTransport
{
    ValueTask<AgentToolTransportResponse> SendAsync(
        AgentToolTransportRequest request,
        CancellationToken cancellationToken = default);
}

This package deliberately contains no HttpClient, no base address, no token, no proxy policy and no retry. Those are environment decisions, and a foundation that guesses them is wrong in the first deployment that differs. The Runtime's surface happens to be HTTP, so a host that talks to it writes roughly this much and nothing more:

sealed class HttpTransport(HttpClient client, Uri baseAddress) : IAgentToolTransport
{
    public async ValueTask<AgentToolTransportResponse> SendAsync(
        AgentToolTransportRequest request, CancellationToken cancellationToken = default)
    {
        var route = request.Route!;
        var path = route.Path;
        foreach (var parameter in route.Parameters)
        {
            // The transport decides where a value comes from: this surface names repositories with
            // the `.git` suffix, which is surface knowledge and therefore not ours to assume.
            var value = request.PathParameters.TryGetValue(parameter, out var supplied)
                ? supplied
                : parameter == "application" ? request.Application
                : throw new InvalidOperationException($"No value for '{parameter}'.");
            path = path.Replace("{" + parameter + "}", Uri.EscapeDataString(value), StringComparison.Ordinal);
        }

        using var message = new HttpRequestMessage(
            new HttpMethod(route.Method), new Uri(baseAddress, path.TrimStart('/')));
        if (request.IdempotencyKey is not null)
            message.Headers.TryAddWithoutValidation("Idempotency-Key", request.IdempotencyKey);
        if (request.Arguments is not null && route.Method is "POST" or "PUT" or "PATCH")
            message.Content = new StringContent(request.Arguments.ToJsonString(), Encoding.UTF8, "application/json");

        using var response = await client.SendAsync(message, cancellationToken);
        return new AgentToolTransportResponse(
            (int)response.StatusCode,
            await response.Content.ReadAsStringAsync(cancellationToken));
    }
}

Register it and the agent has a working tool surface. Assemble the catalog into an agent kernel the same way — take IAgentToolCatalog.Manifest.Tools, project each tool onto the kernel's function shape, and hand IRuntimeAgentToolInvoker to the executor. Business-specific tools belong in a contribution of your own, not in a fork of this module.

Contracts it publishes

Generated, not hand-maintained: acceptance/scripts/generate-contracts.sh emits them and the acceptance gate compares them byte for byte, so a stale copy cannot ship.

• agent-tools.manifest.json
• runtime-script-job-map.json
• runtime-script-knowledge.schema.json

Wiring

services.AddIToolDevelopmentFoundation();
services.AddMyScriptRuntime(builder =>
{
    builder.AddJavaScriptRuntime();
    builder.AddStandardVGitAgentTools();                       // catalog + job map + route source + invoker
});
services.AddSingleton<IAgentToolTransport, HttpTransport>();    // the host's half
services.AddRuntimeScriptAgentWithNeutralIdentity();           // knowledge queries behind a validated identity
endpoints.MapRuntimeScriptKnowledge();                         // POST /agent/runtime-script-knowledge

Everything is registered with TryAdd..., so a host that replaces any part registers its own first and keeps it.

Boundaries, and the checks that hold them

• The Runtime SDK does not depend on this module; a test asserts it.
• StandardAgentToolJoinKeys refuses an operation it has no row for; a test asserts every join key in the catalog resolves to a route; and the contract generator refuses a route that does not match openapi.json. All three fail loudly instead of shipping a link that resolves to nothing.
• With no transport registered the invoker reports agent_tool_transport_unavailable instead of appearing to work and failing obscurely later.