Skip to content

AIFACTORY-FEAT-030: ToolExecutorHost: gateway delivery

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Tools & MCP Platform (PF-05) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 69 of 185 (Factory code)

ToolExecutorHost is the platform API gateway of bounded context BC-08 (Tool Execution). The API gateway of the Tools & MCP platform (ADR-0028): routes public REST and internal gRPC calls to the 2 services it fronts, validates tokens and scopes, and owns no business state. ToolAdapterService behind it stays the only executor of tools (GW-05). Its own repository is ConnectSoft.AI.SoftwareFactory.ToolExecutorHost.

Delivers ToolExecutorHost (complete)
Stubs —
Realizes adrs: ADR-0012, ADR-0014, ADR-0016, ADR-0017, ADR-0022
Requirements FR-05, FR-06, FUX-05, FUX-07, NFR-02, NFR-04, NFR-05, NFR-10, XL-03, XL-06, XL-10
Depends on —
Sources model/services/tools-mcp/ToolExecutorHost.yaml

Scenarios to trace (6, catalog): SCN-ToolExecutorHost-001 ✓, SCN-ToolExecutorHost-002 ✓, SCN-ToolExecutorHost-003 ✓, SCN-ToolExecutorHost-004 ✓, SCN-ToolExecutorHost-005 ✓, SCN-ToolExecutorHost-006 ✓

AIFACTORY-US-065: ToolExecutorHost routes its platform's calls under a trusted scope

enabling · persona asset-maintainer As an asset maintainer, I want one gateway in front of McpServerRegistryService and ToolAdapterService that validates tokens and scopes, so that no service of the platform is reachable except through its gateway and every call arrives with a scope it can trust.

This is the integration PBI of the Tools and MCP gateway. ADR-0028 re-scopes the former composition host as the API gateway of its platform: ToolExecutorHost routes public REST and internal gRPC calls to the two services the model lists under deployment.fronts, McpServerRegistryService and ToolAdapterService, validates tokens and scopes and owns no business state. It is the only route to the executor, and the executor behind it stays the only component that runs a tool (GW-05, ADR-0022 decision 2): the gateway executes nothing, decides no policy, binds no approval, leases no sandbox and holds no secret. One part of the host runs outside the gateway process (decision D125): in I1 the seven repository read tools execute inside the sandbox of the run, and the host carries the read-tool component of the RepositoryIntelligenceService repository, which it starts inside the sandbox that ToolAdapterService leased, over the workspace mounted read-only (AIFACTORY-US-1509); the gateway process still runs no tool, and the executor still decides, leases and receipts every call. The repository ConnectSoft.AI.SoftwareFactory.ToolExecutorHost is created and scaffolded in I0 by AIFACTORY-TASK-083 of feature repository-and-pipeline-conventions (D140), by the steps of its repository checklist, and this feature starts from that scaffold; it was scaffolded from the pinned API gateway template package with UseFactoryProfile and the gateway role Platform, which fixes persistence, messaging and the actor model to none: the gateway has no relational store, no outbox and no inbox, consumes no event (ADR-0028 amendment on gateways and events) and its only store is the shared cache. The scope of a call is established once from the validated token with the scope accessor of the pinned ConnectSoft.Extensions.AI.Factory.Abstractions package; the gateway copies neither the accessor nor the token contract. It forwards the user token to the fronted service unchanged and exchanges no token, and the fronted service accepts the audience of its own gateway (ADR-0015 amendment D117). The feature is delivered by seven further PBIs: the fronts file and the routes generated from it (AIFACTORY-US-611), token, tenant and scope on every read and sandbox route (AIFACTORY-US-612), the pass-through of a shared-write call (AIFACTORY-US-613), the publication routes of the registry whose gate stays in the service (AIFACTORY-US-614), the two ways a tool call reaches the executor, the gRPC route of the agent hosts and the MCP route (AIFACTORY-US-615), health, capabilities, limits and telemetry with the three failure modes of a gateway (AIFACTORY-US-616), and the read-tool component in the sandbox of the run (AIFACTORY-US-1509). The callers are the agent hosts, which invoke tools with the Factory tool client of the pinned AI libraries under a workload token, and the Studio backend and the command-line client, which read descriptors, servers and receipts with the typed tool gateway client of feature typed-gateway-clients, generated from the OpenAPI document this gateway publishes. RunControlService is the one caller of the internal route of ConfirmToolEffect, by which it records the finding of the Operator on an uncertain tool effect (D121). In I1 the hosted MCP endpoint behind the MCP route serves only calls bound to a run, a step and an attempt, and IDE clients and partner agents arrive with the complete McpServerRegistryService in I5 (D121). A call without a token, with an expired token or with a user token issued for another gateway is answered 401 and a missing scope 403, and no fronted service is called. Every route of this platform addresses a tool, a server, a run or an invocation by its id and none names a project or a tenant in its path, so the gateway forwards under the tenant of the token and the scope of the operation, the fronted service answers 403 for a missing project role and 404 for a resource of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. ToolAdapterService is delivered complete in this increment and McpServerRegistryService thin: a route whose operation the thin registry does not host returns the answer of that service unchanged, and its route class is proven against a fake generated from the fronts entry. The gateway invents no response.

Acceptance criteria

AC1 Given the repository ConnectSoft.AI.SoftwareFactory.ToolExecutorHost created and scaffolded in I0 by AIFACTORY-TASK-083 of feature repository-and-pipeline-conventions with dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.ToolExecutorHost --UseFactoryProfile true --GatewayRole Platform from the pinned template package, when its pipeline runs, then the solution builds, the tests pass with complete reports and a container image is published (ADR-0028, model/services/tools-mcp/ToolExecutorHost.yaml).
AC2 Given a valid token for a route of each fronted service, when the call passes the gateway, then the scope is established once from the token through the scope accessor of the pinned abstractions package, the call is forwarded with the token unchanged, the tenant, the correlation id and the trace context, the fronted service answers and the response returns unchanged, as AIFACTORY-US-612 to AIFACTORY-US-615 prove per route class (ADR-0015, FR-05).
AC3 Given the generated gateway, when its architecture test runs, then the test fails on a persistence model, an aggregate, a migration or a message consumer, the gateway binds no relational store, no outbox and no inbox, no event of the model lists ToolExecutorHost as a consumer, and no type of the gateway process executes a tool, evaluates a policy or holds an approval, the read-tool component that the host starts inside the sandbox of a run being the one part outside that process (ADR-0028, ADR-0022, model/services/tools-mcp/ToolExecutorHost.yaml).
AC4 Given the gateway deployed with two replicas, when ToolExecutorHost/ToolsHealth is probed and one replica is stopped, then health reports the identity platform and the two fronted services, a replica stays in rotation while it can validate tokens, the other replica keeps serving and nothing is replayed, because the gateway holds no state (ADR-0017, model/services/tools-mcp/ToolExecutorHost.yaml).
Traces: services ToolExecutorHost, McpServerRegistryService, ToolAdapterService
Traces: apis ToolExecutorHost/ToolsHealth
Traces: adrs ADR-0015, ADR-0017, ADR-0022, ADR-0028
Traces: requirements FR-05
Depends on AIFACTORY-US-611, AIFACTORY-US-612, AIFACTORY-US-613, AIFACTORY-US-614, AIFACTORY-US-615, AIFACTORY-US-616, AIFACTORY-US-1509, feature:repository-and-pipeline-conventions, feature:component-api-gateway-template, feature:component-extensions-ai
Sources model/services/tools-mcp/ToolExecutorHost.yaml, model/gateways.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/capability-tools/tools/services/tool-executor-host/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2442 Deployment values of the gateway: replica range, ports, probes and the address of each fronted service operations The deployment manifest of the gateway states the replica range 2 to 16, the ports https 7800 and grpc 7802, the liveness and readiness probes on the health operation and one base address per fronted service from configuration, as model/services/tools-mcp/ToolExecutorHost.yaml records them; the silo port 11800 and the gateway port 30800 that the same model file carries are not exposed, because the Platform role has no actor model and nothing listens on them, and that the model file lists them is reported to the owner; the same image runs in the saas-default, hybrid, on-prem and hybrid-compute topologies with the identity authority of the profile from ConnectSoftIdentityPlatform:Authority (ADR-0017). ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-792 Verify tool-executor-host-routes-its-platform by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of the repository; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC4 of AIFACTORY-US-065, that is the scaffold of the Platform role, the scope established once and forwarded, the architecture test with its rule that no type of the gateway executes a tool, and, for AC4, the acceptance test of feature TwoReplicas, which hosts two instances of the gateway behind one test balancer with the fakes of the fronted services, probes ToolExecutorHost/ToolsHealth on both, stops one instance and asserts that the other keeps serving and that no call is replayed. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost

AIFACTORY-US-611: Tools and MCP fronts file: named clients and REST and gRPC routes of the two fronted services, generated at build

enabling · persona platform-admin As a platform admin, I want the route table of the Tools and MCP gateway generated from the list of services it fronts, so that every operation of the platform has exactly one route with its scope and class and no forwarding code is written by hand.

The API gateway template is a custom gateway with controllers, use cases and named clients and is no reverse proxy, so a route exists only when it is declared. Under UseFactoryProfile the generated solution holds a build-time source generator that reads a fronts file on every build and emits one named HTTP client and one gRPC client per fronted service, the REST and gRPC routes that forward to them and the route table (feature component-api-gateway-template). This PBI writes the fronts file of the Tools and MCP platform. It lists the two services of deployment.fronts in model/services/tools-mcp/ToolExecutorHost.yaml, each with its base addresses from configuration and its operations in the shape of the apis section of its service file: name, method and path or gRPC method, scope, side-effect class, idempotency and, for a gRPC method, its streaming. For McpServerRegistryService these are six REST operations and the two methods of McpRegistry; for ToolAdapterService six REST operations and the three methods of ToolExecutor, of which Invoke is a server stream. The REST operations are the public surface that the Studio backend and the clients call, with one exception: ConfirmToolEffect of ToolAdapterService is an internal operation whose one caller is RunControlService (D121), so its route admits no user token and is left out of the public OpenAPI document. The gRPC methods are the internal surface the agent hosts call. Each route carries the scope and the side-effect class of its operation, which is what the route class PBIs of this feature enforce. A test lists the emitted route table against the file and against the two service files of the model, so an operation of the model without a route, a route without an operation, a service named twice or a route named twice fails the build with the entry named. A path that no route matches is answered 404. The gateway adds no operation of its own beyond ToolsHealth and ToolsCapabilities, transforms no payload and composes no response from two services. The fronts file lists every operation of the model, also the five REST operations the thin registry does not host yet, so the complete registry of I5 needs no change of the gateway; until then such a route forwards and returns the answer of the thin service unchanged. The fronts file alone decides which routes are hosted. The option Tools:Host:FrontedServices of the model is bound at startup and compared with the fronts file, and a difference in either direction fails startup with the name; it is not reloadable. Its modelled default names the two services by their service ids, McpServerRegistryService and ToolAdapterService, and equals the service set of deployment.fronts (D121), so an entry of the fronts file needs no second name for its service. The gateway publishes the OpenAPI document of its public REST routes, from which feature typed-gateway-clients generates the tool gateway client.

Acceptance criteria

AC1 Given the fronts file of the Tools and MCP platform, when the gateway builds, then one named HTTP client and one gRPC client exist per service of deployment.fronts and one route per REST operation and gRPC method of McpServerRegistryService and ToolAdapterService, twelve REST routes and five gRPC routes, each with the scope, side-effect class and idempotency of the operation, and the route table test passes against model/services/tools-mcp/ToolExecutorHost.yaml and the two service files it fronts (ADR-0028).
AC2 Given an operation removed from the file, a route named twice or a service named twice, when the gateway builds, then the build fails with the entry named; given Tools:Host:FrontedServices at its modelled default, which names the two service ids of deployment.fronts, when the gateway starts, then startup succeeds; given a value of the option that differs from the services of the fronts file, then startup fails with the differing name; given a path no route matches, when it is called, then the answer is 404 and no fronted service is called (ADR-0028, model/services/tools-mcp/ToolExecutorHost.yaml).
AC3 Given a fake of each fronted service, when one REST route and one gRPC route per service are called with a valid token, then each call reaches the fake of its service with the authorization header, which carries the token of the caller unchanged because the gateway exchanges no token, the tenant, the correlation id and the trace context, and the response of the fake returns unchanged (ADR-0015, FR-05).
AC4 Given the built gateway, when its OpenAPI document is compared with the REST operations of model/services/tools-mcp/ToolAdapterService.yaml and model/services/tools-mcp/McpServerRegistryService.yaml, then every public REST route is described with its path, scope and response codes and no internal operation appears in it, neither the route of ConfirmToolEffect, whose one caller is RunControlService, nor a gRPC method, so the tool gateway client is generated from it without a hand-written operation (ADR-0028).
Traces: services ToolExecutorHost, McpServerRegistryService, ToolAdapterService
Traces: adrs ADR-0015, ADR-0028
Traces: requirements FR-05
Depends on feature:component-api-gateway-template
Sources model/services/tools-mcp/ToolExecutorHost.yaml, model/services/tools-mcp/ToolAdapterService.yaml, model/services/tools-mcp/McpServerRegistryService.yaml, model/gateways.yaml, docs/planes/capability-tools/tools/services/tool-executor-host/index.md#context-and-boundaries

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-084 Fronts file with the REST and gRPC operations of McpServerRegistryService and ToolAdapterService implementation The fronts file lists the two services of deployment.fronts by their service ids with their base addresses from configuration and every REST operation and gRPC method of their service files with name, path or method, scope, side-effect class, idempotency, streaming and visibility, ConfirmToolEffect being the one internal REST operation; the build emits the named clients, the twelve REST and five gRPC routes and the route table; at startup the option Tools:Host:FrontedServices, whose default names the same two service ids (D121), is compared with the fronts file and a difference in either direction fails startup with the name; a call without a valid token or scope is refused at the gateway by the generated policies. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2443 OpenAPI document of the public REST routes of the gateway contract The build of the gateway emits one OpenAPI document that describes the eleven public REST routes with path, scope, request and response codes as the two service files of the model state them and the two operations of the gateway itself, and holds no internal operation, neither the route of ConfirmToolEffect, which only RunControlService calls (D121), nor a gRPC method; the document is published as a pipeline artifact with the version of the gateway, so that the tool gateway client of feature typed-gateway-clients is generated from it (model/services/tools-mcp/ToolExecutorHost.yaml). ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2444 Fakes of the two fronted services and the token matrix of the acceptance suite fixture The acceptance suite of the gateway holds one fake per fronted service, generated from its fronts entry, that records the headers and the gRPC metadata it received, answers a configured status, streams configured messages on ToolExecutor.Invoke and can stop answering, and tokens for the matrix of role and tenant, including an expired token, an identity token, a user token of another audience and a workload token with and without a service scope (model/services/tools-mcp/ToolExecutorHost.yaml). ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2445 Verify the route table against the fronts file and the model verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=RouteTable"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-611: one route per operation of model/services/tools-mcp/ToolExecutorHost.yaml and the two service files it fronts, the failing builds, the start with the option at its default, the failing startup on an option value that differs from the fronts file, the 404 of an unknown path, one forwarded call per service and protocol and the OpenAPI document compared with the model. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost

AIFACTORY-US-612: A read or sandbox route of the tools platform forwards a call only under a validated token, the tenant of the token and the scope of its operation

behavior · persona observer As an observer, I want my read calls to reach the executor and the registry only with the tenant and scope my token grants, so that I see the descriptors, servers and receipts I am entitled to and nobody reads across a tenant through the gateway.

A caller reaches a read or sandbox operation of the platform through the gateway: an asset maintainer lists tools and servers, a requester reads the tool receipts of a run, an operator opens one invocation, and an asset maintainer dry-runs a call. The read routes are ListTools, GetTool, ListRunToolReceipts and GetToolInvocation of ToolAdapterService and ListMcpServers and GetMcpCapabilities of McpServerRegistryService; the sandbox routes are DryRunTool of ToolAdapterService and DiscoverMcpCapabilities of the registry. A user presents an access token of the authorization server whose one audience is this gateway (ADR-0015 amendment on the audience of a user token); a client that also calls the Control Plane gateway requests a second token. The gateway validates issuer, signature, lifetime and audience through the pinned resource-server library and requires the scope the operation names: factory.tools.read, factory.runs.read or factory.tools.admin. It takes the tenant from the tid claim and overwrites any tenant header of the caller. The scope is established once with the scope accessor of the pinned ConnectSoft.Extensions.AI.Factory.Abstractions package and forwarded: the authorization header with the user token itself, because the gateway exchanges no token and the fronted service accepts the audience of its own gateway (ADR-0015 amendment D117), the tenant in X-Tenant-Id, the correlation id and the trace context. Every one of these routes addresses its resource by an id: a tool, a run, an invocation or a server. A gateway without business state cannot resolve the project or the tenant of such an id, so it checks token and scope and forwards; the fronted service answers 403 for a missing project role and 404 for a resource of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. For a read route the response is served by the fronted service with no side effect. For a sandbox route the service acts inside its own bounds: a dry run executes nothing, and a discovery lists capabilities into bindings without activating a server; the gateway adds no gate of its own to the class. GetMcpCapabilities and DiscoverMcpCapabilities are not hosted by the thin registry of this increment, so their routes return the answer of the thin service unchanged and their class is proven against the fake generated from the fronts entry. The gateway returns every response unchanged with the correlation id and keeps nothing of the call. A call without a token, with an expired token, with an identity token or with a user token issued for another gateway is answered 401 and a token without the scope of the operation 403; in each case no fronted service is called, and the refusal is counted for the route and logged with the correlation id and without the token. A public REST route admits no workload token, because its operation names no service scope. When a fronted service does not answer, its routes answer 503 with a problem response that carries a retry hint and names the service and never its address, and the routes of the other service keep serving.

Acceptance criteria

AC1 Given a user token whose audience is this gateway with factory.tools.read, when the read route of ToolAdapterService/ListTools and of McpServerRegistryService/ListMcpServers is called, then the gateway forwards the call with the user token unchanged in the authorization header, without a token exchange, the tenant of the tid claim, the correlation id and the trace context, the fronted service, which accepts the audience of its own gateway, answers, the response returns unchanged with the correlation id and nothing is written by the gateway (SCN-ToolExecutorHost-004, ADR-0015).
AC2 Given the token matrix of the acceptance suite, when the read routes of both services are called, then a call without a token, with an expired token, with an identity token or with a user token issued for another gateway is answered 401, a token without the scope of the operation 403 and a workload token on a public REST route 403, and in none of these cases a fronted service is called; given a route addressed by a tool, run, invocation or server id, then the gateway forwards under the tenant of the token and the scope of the operation, and the 403 of the fronted service for a missing project role and its 404 for a resource of another tenant return unchanged (SCN-ToolExecutorHost-004, ADR-0015).
AC3 Given a valid user token and a tenant header of the caller that names another tenant, when a read route is called, then the header is overwritten with the tid claim before the call is forwarded and the fake of the fronted service receives the tenant of the token only (SCN-ToolExecutorHost-004, ADR-0015).
AC4 Given a token with factory.tools.read, when the sandbox route of ToolAdapterService/DryRunTool is called, then the call is forwarded under the same token, tenant and scope rules, the gateway adds no gate of its own to the class and the preview of the service returns unchanged; the sandbox route of the registry is proven against the fake generated from the fronts entry, because DiscoverMcpCapabilities arrives with feature mcp-server-registry-service-complete (SCN-ToolExecutorHost-005, model/services/tools-mcp/McpServerRegistryService.yaml).
AC5 Given ToolAdapterService does not answer, when one of its read or sandbox routes is called, then the gateway answers 503 with a problem response that carries a retry hint and names the service and never its address, invents no response, and the read route of McpServerRegistryService/ListMcpServers keeps serving (SCN-ToolExecutorHost-004, SCN-ToolExecutorHost-005, model/services/tools-mcp/ToolExecutorHost.yaml).
Traces: services ToolExecutorHost, McpServerRegistryService, ToolAdapterService
Traces: apis ToolAdapterService/ListTools, ToolAdapterService/DryRunTool, McpServerRegistryService/ListMcpServers
Traces: adrs ADR-0015, ADR-0028
Traces: requirements FR-05, NFR-02
Traces: scenarios SCN-ToolExecutorHost-004, SCN-ToolExecutorHost-005
Depends on AIFACTORY-US-611, feature:component-api-gateway-template, feature:component-extensions-ai, feature:tool-adapter-service, feature:mcp-server-registry-service-thin
Sources model/services/tools-mcp/ToolExecutorHost.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/capability-tools/tools/services/tool-executor-host/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2446 Issuer, audience and scope configuration of the read and sandbox routes implementation The gateway is configured with the authority of ConnectSoftIdentityPlatform:Authority and its own resource as the one audience of a user token; each read and sandbox route is marked as addressed by a resource id only, so the gateway checks token and scope and leaves the project role and the tenant of the resource to the fronted service; the tenant header is overwritten with the tid claim, the scope is established through the scope accessor of the pinned abstractions package and forwarded in the canonical tenant header, the user token is forwarded unchanged in the authorization header and no token is exchanged (ADR-0015 amendment D117); a workload token is refused on a public REST route; refusals are counted per route and logged with the correlation id and without the token. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2447 Verify the read and sandbox routes through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ToolExecutorHost-004\|Scenario=SCN-ToolExecutorHost-005)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-612 over the token matrix, the token received by the fake equal to the user token of the caller, a route addressed by an id whose 403 and 404 come from the fake and return unchanged, the overwritten tenant header, the sandbox route of the registry against the fake generated from the fronts entry and a fake that stops answering. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost

AIFACTORY-US-613: A shared-write route of the tools platform passes the request and its idempotency key through and the gateway keeps nothing between calls

behavior · persona operator As an operator, I want a write that is repeated after a failure, by me or by Run Control when it records my finding, to be applied once, so that a lost answer or a restarted gateway never confirms an effect twice or registers a server twice.

Two REST operations of the platform are of class shared-write. RegisterMcpServer of McpServerRegistryService is public: its caller sends it through the gateway under the token, tenant and scope rules of AIFACTORY-US-612, with factory.tools.admin. ConfirmToolEffect of ToolAdapterService is internal: RunControlService calls it to record the finding of the Operator on an Uncertain invocation, applied or not-applied, when the Operator decides the operator decision of the run, and no operator calls it directly (D121). On this route the gateway admits the workload token of RunControlService when it holds factory.tools.operate, forwards the tenant and the project of the caller unchanged, as it does on an internal gRPC route (ADR-0015 amendment D114), and refuses a user token with 403 before any fronted service is called. Which token RunControlService presents is not stated by the decision, so this is the reading of the delivery and is reported to the owner. RegisterMcpServer declares idempotency key-header: it is called with an Idempotency-Key, the gateway forwards the header unchanged, and the registry applies the request once under its own rule, the same key with the same body returning the same result and the same key with a different body its 409, which returns to the caller unchanged. ConfirmToolEffect is naturally idempotent: the executor returns the same result for the same finding and answers 409 for a different one, and the gateway forwards both answers as they are. The gateway is no party to idempotency. It stores neither a key nor a result, keeps no session and no pending call, has no outbox and writes no event and no audit evidence; the evidence of a confirmation is written by the executor in the transaction of its command. A gateway replica that crashes during a call therefore loses nothing: the replica restarts, nothing is replayed, and the caller repeats the call and receives from the service the result of the one application (failure mode of a gateway replica crash in the model). When the fronted service does not answer, the route answers 503 with a problem response that names the service and carries a retry hint, the other routes keep serving, and the caller repeats the call. A refusal by the gateway, 401 or 403, reaches no fronted service, so it applies nothing. Both routes name only a resource id or none, so the 403 of the fronted service for a missing project role and its 404 for a resource of another tenant (ADR-0015 amendment D113) return unchanged; the service has applied nothing. A missing key, an invalid body and every domain refusal are answers of the fronted service and return unchanged with the correlation id. RegisterMcpServer is not hosted by the thin registry of this increment, so the key-header rule is proven against the fake generated from the fronts entry. The gateway records request count and latency for the route with the status that was returned.

Acceptance criteria

AC1 Given the workload token of RunControlService that holds factory.tools.operate, when the internal shared-write route of ToolAdapterService/ConfirmToolEffect is called with a finding, then the gateway forwards the request with the body, the token and the tenant and project of the caller unchanged, the executor applies it once and its response returns unchanged with the correlation id; the same finding repeated returns the result of the first application and a different finding the 409 of the executor, both unchanged; a user token on this route is answered 403 and reaches no fronted service, because no operator calls the operation directly (SCN-ToolExecutorHost-006, ADR-0015).
AC2 Given the shared-write route of the registry, whose operation declares idempotency key-header, and the fake generated from its fronts entry, when the call arrives with an Idempotency-Key, is repeated with the same key, and is repeated with the same key and a different body, then the header is forwarded unchanged each time, the fake applies the request once, the repeat returns the first result and the third call returns the 409 of the fake unchanged; the gateway has stored neither the key nor a result (SCN-ToolExecutorHost-006, ADR-0028).
AC3 Given a gateway replica stopped while a shared-write call is in flight, when the caller repeats the call through another replica, then the fronted service returns the result of the one application, nothing is replayed by the gateway and no second state change exists (SCN-ToolExecutorHost-006, model/services/tools-mcp/ToolExecutorHost.yaml).
AC4 Given a call without a token, a token that lacks the scope, or a fronted service that does not answer, when a shared-write route is called, then the answer is 401, 403 or 503 respectively and a call the gateway refuses reaches no fronted service; the 403 of the fronted service for a missing project role and its 404 for an invocation of another tenant return unchanged; the 503 names the service and carries a retry hint while the other routes keep serving (SCN-ToolExecutorHost-006, ADR-0015).
Traces: services ToolExecutorHost, McpServerRegistryService, ToolAdapterService
Traces: apis ToolAdapterService/ConfirmToolEffect
Traces: adrs ADR-0014, ADR-0015, ADR-0028
Traces: requirements FR-10, XL-06
Traces: scenarios SCN-ToolExecutorHost-006
Depends on AIFACTORY-US-611, AIFACTORY-US-612, feature:component-api-gateway-template, feature:tool-adapter-service
Sources model/services/tools-mcp/ToolExecutorHost.yaml, model/services/tools-mcp/ToolAdapterService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2448 Forwarded headers of a write route and a stateless call path implementation A shared-write route forwards the Idempotency-Key header where the operation declares one, the body and the established scope unchanged and returns the status and the body of the fronted service unchanged; the route of ConfirmToolEffect is internal, admits the workload token of RunControlService that holds factory.tools.operate with the tenant and project it forwards, and refuses a user token with 403 (D121); no key, body or result is written to the shared cache or to any store, and no event or evidence record is written by the gateway; request count and latency are recorded for the route with the returned status. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2449 Verify the shared-write routes through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ToolExecutorHost-006"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-613 with the fake of ToolAdapterService for ToolAdapterService/ConfirmToolEffect, called under a workload token that holds factory.tools.operate and refused with 403 for a user token, the fake of the registry that applies a key once, a replica stopped during a call, a 403 and a 404 that come from the fake and return unchanged, and a fake that stops answering. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost

AIFACTORY-US-614: A publication route of the registry is forwarded under its scope and the gate of the action stays in McpServerRegistryService

behavior · persona platform-admin As a platform admin, I want the activation and the retirement of an MCP server to be decided by the registry that owns the server, with the gateway only checking who I am and what I may call, so that an approval or an authentication exception is never decided by a component that holds no state.

Two operations of the platform are of class publication: ActivateMcpServer, which approves the bindings of a server and activates it, and RetireMcpServer, after which the descriptors of the server are unhealthy and inactive. Both belong to McpServerRegistryService and need factory.tools.admin. ADR-0028 leaves a platform gateway routing and the validation of tokens and scopes and no business state, and names a gateway that accumulates logic beyond routing and validation as a reason to revisit the decision. The gateway therefore treats these routes as it treats every route: it validates the token, takes the tenant from it, requires the scope the operation names and forwards the call with the established scope. The gate itself is decided where the state is. The registry activates a server only when its handshake and discovery succeeded and its bindings are approved, refuses a server that is reachable beyond the local process without authentication unless a Platform admin recorded the exception with an expiry (ADR-0022 decision 4), answers 409 when the state of the server does not allow the action and 412 when a precondition such as the recorded exception does not hold, and writes McpServerStateChanged in the transaction of its command; whatever gate the registry applies to the action is decided in the registry, and its answer returns unchanged. The gateway evaluates no approval, holds no approval reference, reads no registration and no exception, and writes no audit evidence: AuditService records the evidence from the event of the registry. The answer of the registry, including 409 and 412, returns unchanged with the correlation id. A call without a token is answered 401 and a token without the scope 403, and no fronted service is called. Both routes name only the serverId, so the gateway forwards under the tenant of the token and the scope of the operation, the registry answers 404 for a server of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. When the registry does not answer, the routes answer 503 with a retry hint and the routes of the executor keep serving. Neither operation is hosted by the thin registry of this increment: the fronts file holds their routes, the class is proven against the fake generated from the fronts entry, which answers 200, 409 and 412, and against the deployed thin service the routes return its answer unchanged. The derived default of the scenario made the gateway forward only a request that carries an approval reference; the gate is stated here where the model puts it, in the fronted service.

Acceptance criteria

AC1 Given a user token with factory.tools.admin, when a publication route of McpServerRegistryService is called against the fake generated from its fronts entry that answers 200, 409 or 412, then the gateway forwards the call under the tenant of the token and the scope of the operation, because the route names only the serverId, and returns each answer unchanged with the correlation id, holding no approval reference and writing nothing (SCN-ToolExecutorHost-003, ADR-0028).
AC2 Given a call without a token or with an expired token, or a token that lacks factory.tools.admin, when a publication route is called, then the gateway answers 401 or 403 and no fronted service is called; given a server of another tenant, when the route is called with a valid token, then the gateway forwards and the 404 of the fronted service returns unchanged (SCN-ToolExecutorHost-003, ADR-0015).
AC3 Given the register of gated routes built from the route table, when it is checked, then every route of class publication has a scope and the gateway holds no handler, cache entry or store for an approval, an authentication exception or a server registration; given the registry does not answer, when a publication route is called, then the answer is 503 with a retry hint that names the service and the routes of ToolAdapterService keep serving (SCN-ToolExecutorHost-003, ADR-0022, model/services/tools-mcp/McpServerRegistryService.yaml).
Traces: services ToolExecutorHost, McpServerRegistryService
Traces: adrs ADR-0015, ADR-0022, ADR-0028
Traces: requirements NFR-04, FR-05
Traces: scenarios SCN-ToolExecutorHost-003
Depends on AIFACTORY-US-611, AIFACTORY-US-612, feature:component-api-gateway-template
Sources model/services/tools-mcp/ToolExecutorHost.yaml, model/services/tools-mcp/McpServerRegistryService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0022-mcp-as-tool-protocol.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2450 Fake of the publication operations of the registry and the route class register of the gateway fixture The acceptance suite holds a fake of ActivateMcpServer and RetireMcpServer generated from the fronts entry of McpServerRegistryService that answers 200, 409, 412 and 404; a register test lists every route of class publication from the route table and fails when such a route has no scope or when the gateway holds a handler, a cache entry or a store for an approval, an authentication exception or a server registration (model/services/tools-mcp/ToolExecutorHost.yaml). ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2451 Verify the publication routes through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ToolExecutorHost-003"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-614: the class forwarded under its scope, the answers 409 and 412 returned unchanged, the refusals of the gateway without a call to a fronted service, the 404 of the fake for a server of another tenant returned unchanged, the register of gated routes and a fake that stops answering. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost

AIFACTORY-US-615: A tool call reaches the executor only through the gateway, over the internal gRPC route of the agent hosts or the MCP route, and the gateway adds no gate and keeps no state

behavior · persona requester As a requester, I want every tool call of my run, and every call of a client that speaks MCP, to enter the executor through one authenticated door, so that no path to a tool exists that skips identity, and what the tool may do is still decided by the executor alone.

A tool call reaches ToolAdapterService by two routes of the gateway, and by no other. The first is the internal gRPC surface. An agent host of the Agent Mesh calls ToolAdapterService/ToolExecutor.Invoke with the Factory tool client of the pinned AI libraries, and ToolExecutor.Validate and ToolExecutor.Interrupt beside it; the two methods of McpRegistry are routed the same way. The caller presents a workload token. Such a token carries service scopes, no audience of a user API and no tenant claim, and the gateway admits it only on a route whose operation names a service scope the token holds. For a workload token that holds the service scope that names the fronted service, the gateway forwards the tenant-id and the project metadata of the caller unchanged, because the fronted service reads a forwarded tenant and project only under that scope (ADR-0015 amendment D114); a call without a token is refused with UNAUTHENTICATED and a workload token without the scope with PERMISSION_DENIED, and no fronted service is called. Invoke is a server stream of class production. The gateway forwards the request, relays every message of the stream in order and unchanged up to the receipt, and propagates the deadline and the cancellation of the caller; it buffers no result and writes no message to a store. The class of the route changes nothing at the gateway: schema, permission, policy, classification, approval binding, credentials, sandbox and the receipt are stages of the executor. The request message of Invoke is a tool-invocation-v1 document, which holds the idempotency key and, as optional members since D121, the fencing token of the lease and the tool version; the gateway relays the message as it is and reads none of it. When a gateway replica stops while a stream is open, the caller sees the stream fail and repeats the call under the same idempotency key through another replica, and the executor answers with the existing invocation and its receipt; the gateway replays nothing. A NOT_FOUND of the fronted service for a resource of another tenant returns unchanged, and the attempt that receives it takes the failure class permanent (ADR-0015 amendment D113). When the executor does not answer, the route fails with UNAVAILABLE and the routes of the registry keep serving. The second route is MCP. ToolAdapterService hosts the MCP endpoint of the Factory with the pinned MCP library, and the gateway routes the transports the option Tools:Mcp:Transports names to it. With Tools:Mcp:AuthorizationEnabled at its default true, a request on the MCP route without a valid token is refused at the gateway with 401 and the protected-resource challenge and never reaches the executor; with a token whose audience is this gateway and whose scope carries factory.tools.invoke it is forwarded with the token unchanged, and the endpoint applies the scope of the caller, the scope-mismatch refusal and the pipeline. In I1 the endpoint serves only calls bound to a run, a step and an attempt, and IDE clients and partner agents arrive with the complete McpServerRegistryService in I5 (D121): the endpoint refuses a call whose token carries no run, step and attempt identity, and the gateway, which adds no gate of its own, returns that refusal unchanged. The option is not reloadable. A value of false would expose the endpoint without identity, which ADR-0022 allows only as a documented exception per server; no such exception can be recorded before the complete registry exists, so in this delivery the gateway fails startup when the option is false. The model defines the option as a boolean with the default true and does not forbid the value false, so the startup failure is the behaviour of this delivery until the owner decides how the option relates to the exception recorded per server, and it is reported to the owner as such, not presented as a rule of the model. The gateway routes the streamable HTTP transport. What routing stdio-bridge means for a network gateway the model does not say; a stdio server of the registry is bridged by the executor inside a sandbox, so the gateway accepts the value, routes nothing for it and the question is reported. connectsoft.factory.tools.host.requests counts every call of both routes by service, transport and status.

Acceptance criteria

AC1 Given a workload token that holds the service scope that names ToolAdapterService and the fake of the executor, when ToolAdapterService/ToolExecutor.Invoke is called through the gateway with a tool-invocation-v1 document that holds its idempotency key and the optional members fencingToken and toolVersion, then the message reaches the fake byte for byte with the token, the tenant-id and the project metadata of the caller unchanged, every message of the stream and the receipt are relayed in order and unchanged, the deadline and a cancellation of the caller reach the fake, and the gateway has stored nothing (FR-05, ADR-0015).
AC2 Given a call without a token, a workload token without the service scope, and a user token on an internal gRPC route, when ToolAdapterService/ToolExecutor.Invoke, ToolAdapterService/ToolExecutor.Validate, ToolAdapterService/ToolExecutor.Interrupt or McpServerRegistryService/McpRegistry.ResolveTool is called through the gateway, then the first is refused with UNAUTHENTICATED and the other two with PERMISSION_DENIED and no fronted service is called; a NOT_FOUND of the fronted service for a resource of another tenant returns unchanged (ADR-0015).
AC3 Given a gateway replica stopped while a stream of ToolAdapterService/ToolExecutor.Invoke is open, when the caller repeats the call under the same idempotency key through another replica, then the fake of the executor receives the same key and answers with the one invocation, the gateway replays nothing, and a stopped executor fails the route with UNAVAILABLE while the routes of the registry keep serving (ADR-0028, model/services/tools-mcp/ToolExecutorHost.yaml).
AC4 Given Tools:Mcp:AuthorizationEnabled at its default, when a request arrives on the MCP route without a token, with a token of another audience and with a token that carries factory.tools.invoke, then the first two are refused at the gateway with 401 and never reach the executor and the third is forwarded with the token unchanged over streamable HTTP, and the answer of the endpoint returns unchanged, also its refusal of a call that is bound to no run; given the option set to false, when the gateway starts, then startup fails with the option named, which is the behaviour of this delivery until the owner decides how the option relates to the exception recorded per server, because model/services/tools-mcp/ToolExecutorHost.yaml does not forbid the value (ADR-0022, model/backlog/pbis/component-extensions/component-mcp.yaml).
Traces: services ToolExecutorHost, ToolAdapterService, McpServerRegistryService
Traces: apis ToolAdapterService/ToolExecutor.Invoke, ToolAdapterService/ToolExecutor.Validate, ToolAdapterService/ToolExecutor.Interrupt, McpServerRegistryService/McpRegistry.ResolveTool, McpServerRegistryService/McpRegistry.ListCapabilities
Traces: descriptors tool-invocation-v1
Traces: adrs ADR-0015, ADR-0022, ADR-0028
Traces: requirements FR-05, NFR-02
Depends on AIFACTORY-US-611, feature:component-api-gateway-template, feature:component-extensions-ai, feature:tool-adapter-service, feature:mcp-server-registry-service-thin
Sources model/services/tools-mcp/ToolExecutorHost.yaml, model/services/tools-mcp/ToolAdapterService.yaml, docs/reference/schemas/tool-invocation.schema.json, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/planes/capability-tools/tools/services/tool-executor-host/index.md#context-and-boundaries

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2452 Internal gRPC routes with the service scope of each method and the pass-through of the Invoke stream implementation Each of the five gRPC routes names the service scope a workload token must hold; for a token that holds it the tenant-id and the project metadata of the caller are forwarded unchanged (ADR-0015 amendment D114), a call without a token is answered UNAUTHENTICATED and a token without the scope PERMISSION_DENIED before any call; the route of ToolExecutor.Invoke relays the server stream message by message and unchanged, propagates deadline and cancellation, buffers and stores nothing, and fails with UNAVAILABLE when the executor does not answer. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2453 MCP route to the hosted endpoint of the executor with authorization required at the gateway implementation The gateway routes the streamable HTTP transport of Tools:Mcp:Transports to the MCP endpoint that ToolAdapterService hosts, requires a valid token whose audience is this gateway and whose scope carries factory.tools.invoke while Tools:Mcp:AuthorizationEnabled is true, answers 401 with the protected-resource challenge otherwise, forwards the token unchanged, returns the answer of the endpoint unchanged, also its refusal of a call that is bound to no run, because in I1 the endpoint serves only calls bound to a run, a step and an attempt (D121), fails startup when the option is false as the behaviour of this delivery until the owner decides how the option relates to the exception recorded per server, accepts the value stdio-bridge without routing anything for it, and records connectsoft.factory.tools.host.requests with the transport of each call. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2454 Verify the two routes of a tool call through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=ToolCallRoutes"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-615 against the fake of the executor: the request message of ToolAdapterService/ToolExecutor.Invoke, a tool-invocation-v1 document with its optional members fencingToken and toolVersion, received by the fake byte for byte, the relayed stream with its metadata, deadline and cancellation, the three gRPC refusals, a replica stopped during a stream, a stopped executor, the MCP route with and without a valid token, the refusal of the fake endpoint for a call bound to no run returned unchanged and the failing startup with authorization switched off. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost

AIFACTORY-US-616: Health, capabilities, limits and telemetry of the tools gateway while the identity platform, a fronted service or a replica fails

behavior · persona operator As an operator, I want to see whether the gateway, the identity platform, the executor and the registry answer, and what the executor can do, so that I can tell a failing service from a failing gateway and act on the right one.

An operator, the Studio and the probes of the cluster read the state of the gateway through its two own operations. ToolExecutorHost/ToolsHealth reports liveness and readiness of the gateway with the aggregated health of the two services it fronts and of the identity platform. Liveness needs no token; the detail is served to a caller whose scope carries factory.health.read. The identity platform is the one required dependency of the gateway, and the health check is the detection signal the model names for its failure. What the gateway does when it is unreachable is decided (D117, ADR-0015 amendment). While a cached signing key still validates tokens, the gateway stays in rotation: readiness stays ready, tokens that were already issued keep passing, and from the first failed probe ToolsHealth answers 200 with the health degraded and a detail that names the identity platform as unreachable. The gateway leaves rotation only when no valid key remains, because none was cached or the cached keys expired: readiness turns unready, ToolsHealth answers 503 with a problem response that names the identity platform, and calls are refused, so the gateway fails closed. Liveness keeps answering 200 without a token in both phases. A fronted service is an optional dependency that degrades: when the executor or the registry does not answer, health reports it as unavailable in the detail, its routes answer 503 with a retry hint, and the routes of the other service keep serving. ToolExecutorHost/ToolsCapabilities returns the capabilities of the executor to a caller whose scope carries factory.meta.read: the transports, that is MCP over streamable HTTP, the stdio bridge and native, the sandbox kinds available and the descriptor schema versions the executor supports. The transports come from Tools:Mcp:Transports. The model names no operation of a fronted service that returns the sandbox kinds or the schema versions, and a gateway invents no response, so in this delivery the gateway serves both from its deployment configuration, set to the sandbox kinds of the one pool of the thin ExecutionCapacityService and to tool-invocation-v1, and the missing source is reported to the owner. A call without a token is answered 401 and a token without the scope 403. A call that exceeds the rate limit configured for its route is refused with 429 through the pinned rate-limiting library. The gateway emits connectsoft.factory.tools.host.requests with the dimensions service, transport and status and connectsoft.factory.tools.host.request_duration with service and route, the latency including the fronted service, and carries the trace context to the service; its logs never contain a token, a tool argument, a tool result or a payload (ADR-0019). A replica that crashes is detected by the readiness probe and restarts; because the gateway holds no state, nothing is replayed and callers repeat their call with their idempotency key. The roles of the gateway are Operator, Platform admin and Observer.

Acceptance criteria

AC1 Given the gateway with the identity platform and both fronted services reachable, when ToolExecutorHost/ToolsHealth is called, then liveness answers 200 without a token and a caller with factory.health.read receives 200 with the state of ToolAdapterService, of McpServerRegistryService and of the identity platform (SCN-ToolExecutorHost-001, NFR-17).
AC2 Given the identity platform is unreachable and a cached signing key still validates tokens, when calls arrive and ToolExecutorHost/ToolsHealth is probed, then tokens that were already issued are validated with the cached key, readiness stays ready so the replica stays in rotation, and from the first failed probe health answers 200 with the health degraded and a detail that names the identity platform as unreachable, while liveness keeps answering 200; given no valid key remains, when calls arrive, then they are refused, readiness is unready so the replica leaves rotation, ToolExecutorHost/ToolsHealth answers 503 with a problem response that names the identity platform and no state changes (SCN-ToolExecutorHost-001, model/services/tools-mcp/ToolExecutorHost.yaml).
AC3 Given the registry does not answer, when ToolExecutorHost/ToolsHealth and the routes are called, then health reports that service as unavailable in its detail and still answers 200, its routes answer 503 with a retry hint that names the service and the routes of the executor keep serving (SCN-ToolExecutorHost-001, ADR-0028).
AC4 Given a caller with factory.meta.read, when ToolExecutorHost/ToolsCapabilities is called, then the response is 200 with the transports of Tools:Mcp:Transports and native, the configured sandbox kinds and the supported descriptor schema versions; a call without a token is answered 401 and a token without the scope 403, and nothing is written (SCN-ToolExecutorHost-002).
AC5 Given routed REST, gRPC and MCP calls and a call above the rate limit of its route, when the metrics and logs are read, then connectsoft.factory.tools.host.requests counts every call by service, transport and status, the call above the limit was refused with 429, connectsoft.factory.tools.host.request_duration holds the latency by service and route, and no log record holds a token, a tool argument or a tool result (ADR-0019, model/services/tools-mcp/ToolExecutorHost.yaml).
Traces: services ToolExecutorHost
Traces: apis ToolExecutorHost/ToolsHealth, ToolExecutorHost/ToolsCapabilities
Traces: adrs ADR-0015, ADR-0017, ADR-0019, ADR-0028
Traces: requirements NFR-10, NFR-17
Traces: scenarios SCN-ToolExecutorHost-001, SCN-ToolExecutorHost-002
Depends on AIFACTORY-US-611, feature:component-api-gateway-template, feature:component-observability-factory-conventions
Sources model/services/tools-mcp/ToolExecutorHost.yaml, docs/planes/capability-tools/tools/services/tool-executor-host/index.md#metrics-and-observability, docs/planes/capability-tools/tools/services/tool-executor-host/index.md#failure-and-recovery

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-085 Health, capabilities and telemetry of the gateway implementation The health operation serves liveness without a token and the detail under factory.health.read with the aggregated state of the two fronted services and of the identity platform; while the identity platform is unreachable and a cached signing key still validates tokens, readiness stays ready and the operation answers 200 with the health degraded and the identity platform named in the detail from the first failed probe; when no valid key remains, readiness turns unready and the operation answers 503 with a problem response that names the identity platform (D117); liveness stays at 200 in both phases; the capabilities operation lists the transports of Tools:Mcp:Transports and native, the configured sandbox kinds and the supported descriptor schema versions under factory.meta.read; every routed call records connectsoft.factory.tools.host.requests and connectsoft.factory.tools.host.request_duration with their modelled dimensions and carries the trace context to the service. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2455 Rate limits per route from the configuration of the gateway implementation Each route takes its rate limit from the configuration of the gateway through the pinned rate-limiting library and answers 429 above it; the limit of the route of ToolExecutor.Invoke counts calls and never the messages of a stream, and a refused call reaches no fronted service and is counted in connectsoft.factory.tools.host.requests with its status. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2456 Runbook of the three failure modes of the gateway documentation The repository documentation holds one runbook entry per failure mode of model/services/tools-mcp/ToolExecutorHost.yaml (identity platform unreachable, fronted service unavailable, gateway replica crash) with its detection signal, the expected answers of the gateway and the recovery step; the entry of the identity platform states its two phases, degraded and in rotation while a cached signing key validates tokens, and out of rotation and failing closed when no valid key remains (D117, NFR-17); the entry of the replica crash states that a caller of ToolExecutor.Invoke repeats the call under its idempotency key. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-2457 Verify health, capabilities, limits and telemetry through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ToolExecutorHost-001\|Scenario=SCN-ToolExecutorHost-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-616 with the identity platform stopped while a cached key validates tokens (readiness ready, health 200 and degraded), without a cached key and after the cached key expired (readiness unready, health 503), one fake stopped, the capabilities document, a call above its limit and the log scan for tokens and payloads. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost

AIFACTORY-US-1509: ToolExecutorHost starts the read-tool component of the repository intelligence inside the sandbox of the run over the workspace mounted read-only

behavior · persona operator As an operator, I want the seven repository read tools of a run to execute inside the sandbox of that run, so that no deployed service reads a workspace from outside a sandbox before the complete repository intelligence of I5.

In I1 the seven repository read tools (list-files, search-text, search-symbols, find-references, read-range, get-dependencies and get-git-diff) are not reached by a call to a deployed RepositoryIntelligenceService (decision D125). They execute inside the sandbox of the run, where the sandbox lease mounts the workspace of the run read-only, and ToolExecutorHost runs there the read-tool handlers of the RepositoryIntelligenceService repository. The pipeline of that repository publishes the handlers as a tool component, a package beside the container image of the service, which answers the seven methods of RepositoryIntelligence with the same request and reply messages and the same golden argument shapes as the complete service (feature repository-intelligence-service-thin). This PBI fixes the form in which the host takes that component. The host references the package at one pinned version as a library dependency, the dependency of kind library that model/services/tools-mcp/ToolExecutorHost.yaml records as required and fail-fast: a host whose pinned component cannot be loaded does not turn ready. When ToolAdapterService has leased the sandbox of a read tool (feature tool-adapter-service), the host starts the component inside that sandbox and nowhere else; the component reads only the workspace the lease mounts, through the workspaceRef of the lease, holds no secret, opens no network connection and references no store and no messaging profile, so it runs with the network of the sandbox closed. The gateway process itself still runs no tool and keeps no state, and the executor still decides the policy, leases the sandbox, sanitizes the result and writes the receipt; the component returns its reply to the executor, and a read tool that is not answered ends Failed with the failure class transient in the executor. Arguments that do not match the golden shape of the method are refused by the component with INVALID_ARGUMENT, and a request whose invocation names another workspace than the workspaceRef of the lease is refused the same way. The component version is pinned with the other packages of the host and changes only with a new version of the host, so the component in the sandbox and the deployed service of I5 answer the same contract without a contract change. How the executor addresses the component once the host has started it in the leased sandbox is not stated by the model and is reported to the owner; this delivery proves the start, the mount and the contract against a sandbox fixture.

Acceptance criteria

AC1 Given the host built with the pinned package of the read-tool component, when it starts, then the component is loaded at the pinned version and readiness turns ready; given the package cannot be loaded, then readiness stays unready and no route is served as ready (model/services/tools-mcp/ToolExecutorHost.yaml, model/backlog/pbis/knowledge/repository-intelligence-service-thin.yaml).
AC2 Given a sandbox fixture leased for a read tool with the workspace of a run mounted read-only, when the host starts the component in it and RepositoryIntelligenceService/RepositoryIntelligence.ListFiles, RepositoryIntelligenceService/RepositoryIntelligence.SearchText and RepositoryIntelligenceService/RepositoryIntelligence.ReadRange are called with arguments in their golden shapes, then each answers from the mounted workspace only, a write to the workspace and a network connection from the component fail, and a path outside the workspace is refused (model/services/knowledge/RepositoryIntelligenceService.yaml).
AC3 Given the component started in the sandbox fixture, when RepositoryIntelligenceService/RepositoryIntelligence.SearchSymbols, RepositoryIntelligenceService/RepositoryIntelligence.FindReferences, RepositoryIntelligenceService/RepositoryIntelligence.GetDependencies and RepositoryIntelligenceService/RepositoryIntelligence.GetHistory are called with arguments that do not match their shape or with an invocation that names another workspace than the workspaceRef of the lease, then each is refused with INVALID_ARGUMENT and nothing is read (docs/reference/schemas/tool-invocation.schema.json).
AC4 Given the architecture test of the host, when it runs, then the component is started only inside a leased sandbox, the gateway process executes no tool, holds no state and evaluates no policy, and no deployed instance of RepositoryIntelligenceService is called for a read tool (ADR-0028, ADR-0022, model/services/tools-mcp/ToolExecutorHost.yaml).
Traces: services ToolExecutorHost, RepositoryIntelligenceService, ToolAdapterService
Traces: apis RepositoryIntelligenceService/RepositoryIntelligence.ListFiles, RepositoryIntelligenceService/RepositoryIntelligence.SearchText, RepositoryIntelligenceService/RepositoryIntelligence.SearchSymbols, RepositoryIntelligenceService/RepositoryIntelligence.FindReferences, RepositoryIntelligenceService/RepositoryIntelligence.ReadRange, RepositoryIntelligenceService/RepositoryIntelligence.GetDependencies, RepositoryIntelligenceService/RepositoryIntelligence.GetHistory
Traces: tools list-files, search-text, search-symbols, find-references, read-range, get-dependencies, get-git-diff
Traces: adrs ADR-0022, ADR-0028
Traces: requirements FR-05, XL-03
Depends on feature:repository-intelligence-service-thin, feature:component-api-gateway-template
Sources model/services/tools-mcp/ToolExecutorHost.yaml, model/services/knowledge/RepositoryIntelligenceService.yaml, model/backlog/pbis/knowledge/repository-intelligence-service-thin.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-6121 Pinned reference of the read-tool component package and its load check at start implementation The host references the package of the read-tool component that the pipeline of ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService publishes, at one pinned version beside the other packages of the host; a readiness check reports unready while the component cannot be loaded. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-6122 Start of the read-tool component inside the leased sandbox of a read tool over the workspace mounted read-only implementation The host starts the component only inside the sandbox that ToolAdapterService leased for a read tool, with the workspace of the lease mounted read-only, the network of the sandbox closed and no secret, store or messaging profile; the component answers the seven methods of RepositoryIntelligence there and returns its reply to the executor, and the gateway process runs no tool and keeps no state. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-6123 Sandbox fixture with a workspace mounted read-only for the acceptance suite of the host fixture The acceptance suite holds a sandbox fixture that mounts a workspace of a fixture run read-only with a closed network, a lease document with its workspaceRef, golden arguments of the seven tool methods and arguments that do not match them, and an invocation that names another workspace. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost
AIFACTORY-TASK-6124 Verify the read-tool component in the sandbox through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=ReadToolComponent"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1509: the load check with a missing package, the seven methods answered from the mounted workspace of the sandbox fixture, the refused write and network connection, the refused mismatched shapes and foreign workspace, and the architecture test that the component starts only inside a leased sandbox. ConnectSoft.AI.SoftwareFactory.ToolExecutorHost