ToolExecutorHost¶

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.


Bounded context	BC-08 Tool Execution
Platform / plane	Tools & MCP Platform / Capability & Tools
Deployment granularity	standalone host
Status	target · `ConnectSoft.Factory.Tools`
Built from	connectsoft-microservice · libraries: connectsoft-extensions-model-context-protocol, connectsoft-extensions-ai, connectsoft-extensions-saas-abstractions, connectsoft-extensions-saas-asp-net-core, connectsoft-extensions-messaging-model, connectsoft-extensions-messaging-model-orleans, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-audit-net, connectsoft-extensions-rate-limiting, connectsoft-extensions-observability
Decisions	ADR-0012, ADR-0014, ADR-0016, ADR-0017, ADR-0022
Traceability	`FR-05` `FR-06` `FUX-05` `FUX-07` `NFR-02` `NFR-04` `NFR-05` `NFR-10` `XL-03` `XL-06` `XL-10`

Purpose and responsibilities¶

Models must not receive uncontrolled access to the host machine (original handoff §35). ToolExecutorHost is the one process in which tools execute: it composes ToolAdapterService (the governed executor) and McpServerRegistryService, serves the Factory's own authenticated MCP endpoint to IDE clients and partners through GW-05, consumes external MCP servers through connections, bridges stdio servers inside sandboxes, and brokers sandboxes from Execution Capacity and credentials from the Secret Broker. The agent template's unauthenticated MCP default (verification of 2026-10-08) is closed here: authentication is on by default (ADR-0022).

Context and boundaries¶

flowchart LR
    S["ToolExecutorHost"]
    AgentRuntimeWorker["AgentRuntimeWorker"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    ext_generated_products["ext-generated-products"] -->|sync-http| S
    S -->|grpc| GovernanceHost["GovernanceHost"]
    S -->|grpc| ControlPlaneApi["ControlPlaneApi"]
    S -->|grpc| RuntimeCloudHost["RuntimeCloudHost"]
    S -->|grpc| KnowledgeHost["KnowledgeHost"]
    S -->|grpc| IntegrationHost["IntegrationHost"]
    S -->|library| ext_mcp_library["ext-mcp-library"]
    S -->|sync-http| ext_identity_platform["ext-identity-platform"]

Hold "Alt" / "Option" to enable pan & zoom

flowchart LR
    subgraph Host["ToolExecutorHost (2 to 16 replicas)"]
        direction TB
        MCPx["Exposed MCP server (authenticated)"]
        Exec["ToolAdapterService<br/>pipeline, receipts"]
        Reg["McpServerRegistryService"]
        Bridge["stdio bridge in sandbox"]
    end
    RT["AgentRuntimeWorker"] -- "Invoke with fencing token" --> Exec
    IDE["IDE clients, partner agents via GW-05"] --> MCPx --> Exec
    Exec --> Reg
    Exec -- "decisions, credentials" --> GOV["GovernanceHost"]
    Exec -- "sandbox leases" --> RC["RuntimeCloudHost"]
    Exec -- "approvals, usage, environment class" --> CP["ControlPlaneApi"]
    Exec --> KH["KnowledgeHost (knowledge and repository tools)"]
    Exec --> IH["IntegrationHost (connections)"]
    Exec --> MCPc["Consumed MCP servers"]
    Exec --> SQL["('tools-sql')"]

Hold "Alt" / "Option" to enable pan & zoom

Domain model¶

None modelled

No aggregates are modelled for this item yet.

No entities modelled.

Entities and value objects¶

None modelled

No entities or value objects are modelled for this item yet.

Data model and storage¶

Store	Role	Engine / profile	Tables
Tool execution store	primary	azure-sql / nhibernate-sqlserver	—
Cache and coordination	cache	redis / azure-cache	—

None modelled

No tables are modelled for this item yet.

APIs¶

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
`GET`	`/tools/health`	ToolsHealth	`factory.health.read`	read	natural	GW-01	Liveness, readiness and dependency health (store, policy engine, secret broker, sandbox capacity, registered MCP servers).
`GET`	`/tools/meta/capabilities`	ToolsCapabilities	`factory.meta.read`	read	natural	GW-03	Executor capabilities: transports (MCP streamable HTTP, stdio bridge, native), sandbox kinds available, supported descriptor schema versions.

None modelled

No gRPC methods are modelled for this item yet.

Messages¶

None modelled

No events are modelled for this item yet.

None modelled

No commands are modelled for this item yet.

None modelled

No consumed events are modelled for this item yet.

Workers and jobs¶

None modelled

No workers are modelled for this item yet.

Actors and grains¶

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows¶

None modelled

No sagas are modelled for this item yet.

Options and configuration¶

Section	Key	Type	Default	Reloadable	Secret	Summary
`Tools:Host`	`EnabledModules`	string[]	`[executor, mcp-registry]`	no	no	Modules composed into this host.
`Tools:Mcp`	`AuthorizationEnabled`	bool	`true`	no	no	MCP endpoints require authentication by default (ADR-0022 closes the unauthenticated default of the agent template).
`Tools:Mcp`	`Transports`	string[]	`[streamable-http, stdio-bridge]`	no	no	Transports the host serves and consumes.
`OrleansMessaging`	`ServiceName`	string	`tools`	no	no	Messaging profile service name.

Metrics and observability¶

Metric	Instrument	Unit	Dimensions	Summary
`connectsoft.factory.tools.host.requests`	counter	{request}	module, transport, status	Requests by module and transport.
`connectsoft.factory.tools.host.sandbox_capacity`	gauge	{sandbox}	kind, region	Sandboxes available from capacity.

Security¶


Authentication	client-credentials
Scopes	`factory.health.read` (Health probes.); `factory.meta.read` (Capability metadata.)
Roles	Operator, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	spend
Secrets	`tools-sql` (key-vault, rotate 90 d); `messaging-transport` (key-vault, rotate 90 d); `mcp-signing-key` (key-vault, rotate 90 d)

Dependencies¶

Outbound

Target	Kind	Purpose	Failure mode	Required
GovernanceHost	grpc	Policy decisions and short-lived credentials from the Secret Broker.	fail-fast	yes
ControlPlaneApi	grpc	Approval validation, usage recording, environment class.	fail-fast	yes
RuntimeCloudHost	grpc	Sandbox and workspace leases from Execution Capacity (BC-26).	fail-fast	yes
KnowledgeHost	grpc	Knowledge and repository tool backends.	degrade	yes
IntegrationHost	grpc	Connections for tools that reach external systems.	degrade	yes
ext-mcp-library	library	MCP hosting and governance toolkit integration.	fail-fast	yes
ext-identity-platform	sync-http	Workload identities and per-attempt token validation.	fail-fast	yes

Inbound

Target	Kind	Purpose	Failure mode	Required
AgentRuntimeWorker	grpc	Tool invocations of attempts with fencing tokens.	—	yes
StudioBff	sync-http	Descriptor, server and receipt views.	—	yes
ext-generated-products	sync-http	IDE clients and partner agents calling MCP tools through GW-05.	—	yes

Failure and recovery¶

Scenario	Detection	Recovery	Data impact	RTO (min)
Policy engine unreachable	decision failures	fail closed; no tool executes without a decision	none	15
Sandbox capacity exhausted	lease denied	invocation queued within the attempt budget then fails as transient; capacity alerts	none	30
Host crash during a long tool	invocation grain inactive with lease held	reconciler marks the invocation Uncertain and the attempt sees it; sandbox reaped	possible unconfirmed effect flagged	10

NFR targets¶

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment¶


Granularity	standalone host
Topologies	saas-default, hybrid, on-prem, hybrid-compute
Runtime	aks; replicas 2–16
Ports	https 7800, grpc 7802, silo 11800, gateway 30800

The shell sandbox is a separate trust boundary from the host process (GW-05 role): the host never runs commands itself, it leases sandboxes.

Current implementation¶

ConnectSoft.Extensions.ModelContextProtocol provides MCP hosting, OAuth protected-resource metadata and governance toolkit integration with authorization disabled by default; the agent template exposes a sample MCP tool that calls AIAgent.RunAsync directly. No executor pipeline, descriptor registry, receipt or sandbox broker exists.

Later capabilities¶

Regional executor pairs; computer-use sandboxes at scale; an executor profile that runs inside a customer's network for the hybrid profile only.

Decisions and traceability¶

Family	Ids
FR	FR-05, FR-06
FUX	FUX-05, FUX-07
NFR	NFR-02, NFR-04, NFR-05, NFR-10
XL	XL-03, XL-06, XL-10

Tools & MCP overview · ToolAdapterService · McpServerRegistryService · Deployment
Tools & MCP Platform microservices · bounded contexts · APIs · events · data model
Services catalog · Ownership map

ToolExecutorHost¶

Purpose and responsibilities¶

Context and boundaries¶

Domain model¶

Entities and value objects¶

Data model and storage¶

APIs¶

Messages¶

Workers and jobs¶

Actors and grains¶

Sagas and long-running flows¶

Options and configuration¶

Metrics and observability¶

Security¶

Dependencies¶

Failure and recovery¶

NFR targets¶

Deployment¶

Current implementation¶

Later capabilities¶

Decisions and traceability¶

Related¶