InfraTwin

InfraTwin lets engineers and WebMCP agents share one live network ChangePlan, using deterministic analysis and verified optimization to catch risky changes before production.

Comment

Inspiration

Network changes rarely fail in isolation. A maintenance outage in one region, expected traffic growth somewhere else, and a capacity restriction on another corridor can combine into a failure hundreds of miles away from the original change.

That makes network change planning a coordination problem as much as a routing problem. Engineers have operational context that is difficult to encode completely in advance: a link may technically support an upgrade but be unavailable during a maintenance window, a corridor may be protected for business reasons, or an apparently cheap mitigation may conflict with another planned change.

Traditional planning tools can model topology and run analyses, while AI assistants can explore ideas and explain results. The gap appears when the plan changes while the agent is reasoning. If the engineer selects a different resource, locks infrastructure, modifies traffic expectations, or invalidates an old proposal, the agent needs to operate on that exact new state rather than on a detached snapshot.

InfraTwin started from a simple question: what if a network ChangePlan became a shared live artifact that an engineer and an agent could reason over together, while deterministic systems remained responsible for the engineering truth?

The goal was not to build a chatbot attached to a topology viewer. It was to build an engineering workbench where human judgment, agent exploration, and machine-checkable computation each have a clear role.

What InfraTwin does

InfraTwin is a browser-native network change-planning, resilience, and optimization workbench. Engineers can model maintenance outages, restorations, traffic growth, individual demand changes, capacity upgrades, budgets, target utilization, and infrastructure that must not be modified, then analyze the consequences before those changes reach production.

The underlying network remains separate from the editable ChangePlan. Proposed changes are therefore reversible and inspectable rather than silently modifying the canonical model. Analysis and optimization operate on the derived planned state while preserving provenance back to the original network and the human or agent action that created each change.

The flagship workflow demonstrates one continuous human-agent decision loop.

An engineer schedules a Northeast-to-Central backbone link for maintenance. A WebMCP agent sees that exact live plan and adds the expected 20% growth in Payments traffic. InfraTwin runs deterministic routing and capacity analysis and discovers that the combined change creates an overload on a different Southeast-to-Central corridor, reaching 85% utilization against an 80% target.

The agent asks InfraTwin for the cheapest modeled mitigation and initially receives a capacity-oriented proposal. The engineer then supplies information the optimizer did not previously have: that corridor cannot be modified during this change window. The engineer locks it directly in the shared workspace.

That edit immediately changes the valid design space. The old proposal becomes stale rather than remaining silently actionable, and the agent can no longer continue as if the earlier assumptions still held.

The agent replans under the new human constraint. With adaptive routing enabled, InfraTwin finds a different design that changes 54 routing allocations, reduces modeled peak utilization from 85% to 67%, and requires no new capacity or new links.

The proposal is not labeled safe or verified simply because an optimizer returned it. InfraTwin reconstructs the proposed design and checks its routing, demand conservation, capacity, utilization, restrictions, locks, budget, objective, scenario identity, and other declared constraints before it can receive a VERIFIED state.

This division of responsibility is intentional:

The human provides intent, operational knowledge, constraints, and approval. The agent explores the decision space and revises alternatives. InfraTwin supplies the deterministic evidence connecting them.

Why WebMCP?

WebMCP is central to InfraTwin rather than an alternate transport layer for backend APIs.

The network and its unsaved ChangePlan exist inside the live browser workspace. Through native WebMCP capabilities, the agent can inspect the same current selection, plan state, human restrictions, analysis evidence, proposals, and verification freshness that the engineer is working with.

That shared state matters because engineering intent changes continuously during planning.

A conventional integration can give an agent a serialized representation of an application and expose operations over it, but synchronization becomes another problem to manage. The human may have selected a different link, edited a constraint, invalidated a proposal, or changed the current plan after the agent began reasoning.

InfraTwin instead treats the browser workspace itself as the collaboration surface.

When the engineer adds a lock, the agent sees the new restriction through the same application state. When a plan edit makes an earlier analysis obsolete, that evidence becomes stale. When the semantic state no longer supports a capability, InfraTwin can revoke that capability rather than leaving an invalid action available and hoping the model decides not to use it.

That is one of the most important ideas behind the project: mathematical and product preconditions can become capability preconditions.

For example, violation-specific tools only become useful when current analysis contains a violation. Proposal actions require a current proposal. Human edits can invalidate previously valid proposal actions. Long-running operations are also bound to the semantic revision they started from so that a result computed against an obsolete plan cannot later publish itself as authoritative.

This creates a much stronger human-agent interaction than simply giving an agent buttons to press.

The engineer can change the problem while the agent is working, and the agent continues inside the human's new decision boundary.

What people and agents can do together

InfraTwin is designed around complementary strengths rather than attempting to automate the engineer out of the loop.

Humans are good at supplying context that may not exist in the mathematical model: which maintenance work is politically or operationally possible, which infrastructure must remain untouched, which services matter most, and whether a proposed tradeoff is acceptable.

Agents are useful for exploring a large decision space, connecting evidence across views, requesting analyses, proposing mitigations, and quickly revisiting alternatives when assumptions change.

The deterministic engine handles the part neither should improvise: routing, capacity calculations, resilience analysis, optimization, and verification.

That means a workflow can evolve naturally:

An engineer expresses intent. The agent explores the consequences. InfraTwin produces evidence. The engineer adds a constraint. The old answer becomes invalid. The agent replans. InfraTwin verifies the new proposal. The engineer retains final approval.

Before WebMCP, implementing that interaction cleanly would typically require synchronizing human UI state with a separate agent-side representation or building a parallel backend state model. InfraTwin instead lets both participants operate through the same browser-local artifact.

Evidence, not model guesses

InfraTwin deliberately separates agent reasoning from engineering computation.

The language model can inspect state, explain evidence, add or revise plan changes, request analysis, investigate violations, and explore mitigation alternatives. It does not calculate network feasibility by generating prose.

InfraTwin's deterministic engine performs single-shortest-path and ECMP routing, utilization and capacity analysis, bottleneck and min-cut analysis, bounded N-1 contingency evaluation, and solver-backed optimization.

Adaptive network design uses deterministic candidate paths and HiGHS LP/MILP optimization. Candidate routes are bounded and reproducibly generated, and the optimizer operates only over declared engineering actions. If candidate links are enabled, their endpoints, capacity, direction, routing weight, and cost must already be declared; the optimizer does not invent infrastructure or prices.

Solver output is treated as a candidate, not as proof.

InfraTwin reconstructs the returned primal decisions and independently checks demand conservation, path continuity, action legality, link loads, utilization constraints, locks and routing restrictions, budget, objective, and scenario identity.

The verification state is also revision-bound. If a human later changes an engineering-relevant assumption, the old verification cannot continue presenting itself as current.

The agent proposes and explains; InfraTwin computes and verifies.

This approach also makes failures useful. A failed plan produces concrete evidence—overloaded links, routes, bottlenecks, contingency rankings, or infeasibility information—rather than only a generic warning.

Adaptive network design

InfraTwin's normal plan analysis uses deterministic SSP or ECMP routing. Adaptive design is a separate, explicitly enabled capability for cases where the current routing model cannot satisfy the engineer's constraints.

The adaptive engine searches a bounded deterministic set of candidate routes and declared design options. It can jointly reason about traffic allocation and allowed infrastructure changes while respecting human locks, routing restrictions, budgets, target utilization, selected scenarios, declared capacity upgrades, and explicitly enabled candidate links.

The flagship demo is a useful example of why this matters. The obvious capacity upgrade is removed from the valid design space by a human lock. Rather than failing back to a generic recommendation, InfraTwin searches the remaining modeled space and finds an alternate traffic allocation that satisfies the declared constraints without adding capacity.

The result is intentionally described as a verified modeled alternative—not as a claim that InfraTwin has discovered the globally optimal architecture for a real production network.

Performance and scale

Keeping this workflow browser-native created a second challenge: sophisticated graph and optimization workloads can quickly become expensive.

InfraTwin uses Web Workers so larger deterministic analyses and optimization operations do not block the interface, while the topology uses adaptive Canvas rendering to remain usable on larger networks.

The adaptive candidate-path engine was also extensively optimized. The original implementation repeatedly rebuilt graph structures and performed expensive shortest-path work inside bounded Yen K-shortest-path searches. After profiling, the engine was redesigned around compiled immutable graph state, deterministic heap-based shortest paths, reusable route structures, semantic caching, and Worker reuse.

On the unchanged benchmark fixtures, cold candidate-path generation improved from:

  • 4.73 s to 0.51 s on 128 nodes / 304 links / 96 demands
  • 41.3 s to 4.0 s on 250 nodes / 600 links / 200 demands
  • 354.6 s to 37.6 s on 500 nodes / 1,200 links / 400 demands

That represents roughly a 9–10× improvement while preserving the existing mathematical formulation and exact path-generation semantics.

The browser workspace itself has been validated on a 500-node, 1,200-link, 400-demand, 12-region synthetic network. Different features intentionally have different compute envelopes: normal deterministic analysis remains considerably more interactive than large adaptive design workloads.

How we built it

InfraTwin is built with Next.js, React, and TypeScript. Normal operation is browser-first: network state, the ChangePlan, analysis, and most optimization workflows remain local rather than depending on a remote application server.

HiGHS runs through WebAssembly for LP/MILP optimization. Web Workers isolate expensive computation from the main interface, and Canvas-based topology rendering supports larger graphs without requiring thousands of DOM elements.

The WebMCP integration uses native document.modelContext capability registration.

Representative capabilities include workspace and selection inspection, ChangePlan authoring, deterministic analysis, contingency execution, violation inspection, mitigation generation, adaptive design, and verification.

Rather than registering every capability permanently, InfraTwin groups and dynamically exposes tools according to current semantic state. Tool lifetimes and stale-state behavior are tested against real document.modelContext.getTools(), executeTool(), and toolchange behavior in a native Chromium environment.

Human UI actions and WebMCP actions pass through the same collaborative application service. They therefore produce the same semantic ChangePlan state, with actor and provenance differences preserved rather than creating separate hidden agent state.

The agent also cannot silently commit a proposed design into the canonical network. Proposals remain proposals until the human explicitly chooses what to accept.

Safety and trust boundaries

Because InfraTwin allows an agent to operate inside a consequential engineering workflow, important constraints are enforced below the prompt layer.

Human locks are hard optimizer constraints, not text instructions to the model. Imported names and metadata are treated as untrusted content. Agent-accessible read tools retain untrusted-content annotations where applicable. Raw WebMCP inputs are validated before they can mutate shared state.

Long-running work is bound to an authority token representing the semantic state from which it began. If a human edits the plan while a Worker or optimizer is still running, obsolete results cannot later publish themselves as current.

Similarly, stale proposals and stale verification results lose their authority immediately after relevant semantic edits.

The general principle is simple: if an action is no longer valid, prefer removing it from the capability space instead of relying on the agent to remember that it should not use it.

Challenges we ran into

The hardest problem was not exposing more WebMCP tools. It was determining when each tool should exist and what should happen when the human changes the state underneath an ongoing agent workflow.

That led to semantic revision hashes, explicit provenance, cancellation authority, dynamic WebMCP registration, stale-state invalidation, and a strict separation between presentation changes and engineering-relevant changes.

A second challenge was maintaining deterministic correctness while optimizing performance. Faster graph algorithms, caching, and Worker reuse are useful only if they preserve exactly the same network semantics. The optimized path engine therefore remains differentially tested against the frozen reference implementation, including candidate paths, restrictions, cache invalidation, topology changes, cancellation, and Pareto variants.

The final major challenge was product clarity. A mathematically correct engineering tool can still be difficult to understand. The final UI work focused heavily on making current plan state, human versus agent actions, stale proposals, deterministic failures, and proposed verified designs visually distinct.

That product work became just as important as the underlying algorithms because a correct result is only useful if an engineer can understand why it happened.

Testing and validation

InfraTwin has a deliberately broad validation surface because the demo makes several strong claims about determinism and shared state.

The repository contains unit and property tests for routing, ECMP, min-cut, optimization, semantic hashing, stale-state handling, locks, cancellation, verification, candidate-path equivalence, cache behavior, and WebMCP capability semantics.

Playwright tests exercise complete browser workflows, including ChangePlan authoring, failure evidence, large-network interaction, adaptive design, and human-agent coactivity.

A separate native WebMCP test path validates capability discovery and execution through the actual document.modelContext host surface rather than only testing a mocked interface.

Benchmarks and permanent CI gates are included so the performance and correctness claims shown in the project can be reproduced from the public repository.

What we learned

The biggest lesson was that WebMCP becomes most interesting when the agent is not simply automating a website but participating in the same evolving artifact as the human.

In InfraTwin, a human action can alter both application state and the mathematical problem the agent is allowed to solve. That makes synchronization, authority, and stale-state handling first-class product concerns rather than implementation details.

We also learned that consequential agent workflows need enforcement boundaries below natural-language instructions. Human locks, capability removal, revision-bound authority, deterministic computation, and independent verification provide guarantees that prompts alone cannot.

Finally, browser-native computation was capable of significantly more than expected. With bounded mathematical formulations, Workers, WebAssembly, caching, and careful rendering, a fairly sophisticated engineering environment can remain local, interactive, and reproducible.

What's next

InfraTwin currently models a deliberately bounded network-planning abstraction rather than a vendor-specific production-network simulator. It does not attempt to reproduce BGP, OSPF, or IS-IS convergence, detailed hardware queueing, ACL behavior, or device-specific configuration semantics.

Future work could add protocol-aware convergence models, richer service-policy constraints, inventory and telemetry integrations, configuration import/export, multi-failure domains, historical demand data, and production change-management integrations.

The broader idea extends beyond networking.

InfraTwin is an example of a class of shared expert workspaces where humans contribute judgment and real-world constraints, agents explore alternatives and coordinate complex workflows, and deterministic systems establish what the evidence actually supports.

For high-consequence work, that combination is more useful than either a fully manual tool or an autonomous agent operating alone.

Built With

Share this project:

Updates

Submission history