LoadGuard 3D

Agent-native 3D truck load planning where WebMCP agents can inspect, plan, validate, and stage proposals while humans retain control over operational execution.

Comment

Inspiration

As AI agents become capable of doing more inside real applications, I kept coming back to one question:

How do we make an agent genuinely useful without allowing it to give itself permission to perform consequential actions?

Logistics gave me a practical way to explore that problem.

Truck loading involves real constraints: available space, weight limits, fragile cargo, delivery order, package dimensions, and operational state. An agent can be very useful here because it can inspect the current situation, coordinate planning, validate a proposal, and prepare the next action.

But there is an important boundary.

If an AI can both create an operational plan and authorize that same plan, then human oversight becomes mostly cosmetic.

That idea became the foundation of LoadGuard 3D.

The agent reasons.
The operator authorizes.
The website defines and enforces the contract.

LoadGuard 3D explores how WebMCP can give agents structured access to meaningful website capabilities while keeping consequential execution under explicit human control.

What it does

LoadGuard 3D is a WebMCP-native 3D truck load-planning workspace.

The application starts with a real operational state. In the main demo scenario, truck TRK-042 already contains eight loaded packages while an urgent, fragile package, MED-901, is still inbound.

The system can create a candidate loading plan that incorporates the new package while respecting the current truck state and package constraints.

The workflow is intentionally separated into stages:

  1. Inspect the current truck state
  2. Retrieve package constraints
  3. Create a candidate load plan
  4. Validate the candidate
  5. Stage the valid proposal
  6. Attempt operational execution
  7. Require human authorization
  8. Execute the exact approved proposal
  9. Protect against duplicate execution

The operator sees the candidate directly in a 3D truck visualization before deciding whether to approve it.

For the demonstration scenario, the candidate reaches:

  • 9 / 9 packages placed
  • 1011 kg total weight
  • 78.4% utilization
  • 0 hard validation violations
  • 2 fragile-cargo review warnings

The important part is what happens next.

If commit_load_plan is called before a human has approved the proposal, LoadGuard returns:

APPROVAL_REQUIRED

The active truck does not change.

The human then reviews the exact staged proposal in the LoadGuard interface and chooses whether to approve or reject it.

Human approval is intentionally not exposed as a WebMCP tool.

After approval, the same operational commit can succeed because the application and database can verify that the exact proposal being executed is the one the operator authorized.

A successful execution returns:

EXECUTED

and advances the truck state revision.

If the same commit is accidentally retried, LoadGuard returns:

ALREADY_EXECUTED

instead of applying the operation twice.

This makes human authorization, execution, and replay protection part of the real operational contract rather than just UI conventions.

How we built it

LoadGuard is built as several cooperating layers rather than one large autonomous-agent function.

WebMCP interface

LoadGuard registers structured capabilities through document.modelContext.

The website exposes exactly seven WebMCP tools:

  • get_load_state
  • get_package_constraints
  • create_load_plan
  • validate_load_plan
  • stage_load_plan
  • commit_load_plan
  • get_action_ledger

I deliberately kept the tools narrow.

Reading truck state is different from creating a candidate. Creating a candidate is different from staging it. Staging is different from operational execution.

Most importantly, there is no approve_load_plan WebMCP capability available to the agent.

The agent can request execution, but it cannot manufacture its own authority.

Deterministic planning

The language model does not generate the package coordinates.

The model or agent orchestrates the workflow, while LoadGuard's deterministic planner computes the spatial candidate.

This was an important design decision because physical placement should not depend on an LLM inventing geometry.

Independent validation

The candidate is validated before it can become a staged proposal.

The validator checks constraints including:

  • truck boundaries
  • collisions between packages
  • weight limits
  • fragility
  • delivery ordering
  • malformed placements
  • unplaced packages
  • complete target-package coverage

A candidate can therefore be rejected independently of the reasoning that requested it.

3D operator workspace

The frontend is built with React and TypeScript, with Three.js / React Three Fiber providing the 3D truck visualization.

The operator can compare the current load with the candidate plan and review:

  • package count
  • weight
  • utilization
  • validation status
  • warnings
  • manifest state
  • candidate geometry
  • approval controls
  • activity history

This gives the human meaningful information before authorization.

Database-enforced authority

Supabase PostgreSQL is used as the authority and persistence layer.

The database stores trucks, packages, load plans, plan items, and an action ledger.

Protected functions enforce the transition from staged proposal to approved proposal to executed state.

The authorization model includes concepts such as:

  • exact proposal hashing
  • approved hash verification
  • state revisions
  • proposal expiry
  • session isolation
  • immutable approved plan items
  • complete target-package coverage
  • idempotent execution

This means the safety boundary is not based on trusting the model to behave correctly.

Even if an agent asks to commit a plan before approval, the operational layer can refuse it.

Technology

The main stack includes:

  • WebMCP
  • React
  • TypeScript
  • TanStack Start / Router
  • Vite
  • Tailwind CSS
  • Three.js
  • React Three Fiber
  • Supabase
  • PostgreSQL
  • Zod
  • Vitest
  • Cloudflare Workers

The project also includes dedicated pages for the live workspace, WebMCP contract, system architecture, and verification evidence so judges and developers can inspect the project at different levels.

Challenges we ran into

Designing the authority boundary

The hardest challenge was not the truck visualization itself.

It was deciding exactly where agent capability should end and human authority should begin.

An early temptation in an agentic workflow is to expose every action as a tool. But if approval were also exposed as a WebMCP tool, the same agent could potentially plan, approve, and execute its own operation.

That would defeat the purpose of human review.

The solution was to make approval a separate human-controlled application state that cannot be produced through the agent capability surface.

Separating candidate state from active state

A proposed load plan needs to be useful before it is executed.

That meant the candidate had to exist independently of the active truck state.

LoadGuard therefore treats the staged plan as a proposal that can be visualized, validated, approved, rejected, or expire without immediately changing the truck.

Making approval refer to the exact plan

A vague approval such as "yes, load the truck" is not sufficient for an operational system.

I wanted the authorization to refer to the exact candidate the operator reviewed.

That led to canonical plan hashing, approved-hash verification, revision checks, proposal expiry, and immutable approved plan items.

If the plan changes after approval, or if the underlying truck state becomes stale, the old authorization should not silently apply to a different operation.

Handling retries safely

Agents and distributed systems can repeat requests.

An operational commit therefore cannot assume it will only ever be called once.

LoadGuard makes execution idempotent. Once a proposal has executed, another commit attempt returns ALREADY_EXECUTED instead of mutating state again.

Making a technical system understandable

LoadGuard combines WebMCP, deterministic planning, validation, 3D visualization, human authorization, database enforcement, and an audit ledger.

A major challenge was presenting all of that without making the interface feel like a developer console.

The final workspace keeps the 3D truck and decision rail central while exposing deeper WebMCP and architecture details through dedicated views.

Accomplishments that we're proud of

The part I am most proud of is that human approval is not just a visual confirmation dialog.

It is part of the system's actual authority model.

A pre-approval operational commit is rejected.

A human can then authorize the exact staged proposal.

Execution succeeds only after that authorization exists.

A repeated execution is safely rejected as already completed.

I am also proud that the project uses WebMCP for a non-trivial operational workflow rather than exposing a single broad "do everything" function.

LoadGuard has seven focused tools covering inspection, constraints, planning, validation, staging, execution, and auditing.

Another accomplishment was keeping the language model out of the physical packing algorithm itself.

The agent can coordinate the workflow, but deterministic application code remains responsible for geometry and the validator independently evaluates the resulting candidate.

Finally, I wanted LoadGuard to feel like a complete product rather than only a technical WebMCP proof of concept.

The finished project includes:

  • a production landing experience
  • an operational 3D workspace
  • human review controls
  • WebMCP documentation
  • architecture documentation
  • verification evidence
  • a public open-source repository
  • a production deployment

What we learned

The biggest lesson from LoadGuard is that building agentic software is not only about deciding what tools an agent should have.

It is also about deciding:

What authority should the agent never possess?

WebMCP makes the application's capabilities explicit, which also makes it possible to think carefully about consequence boundaries.

I learned that narrow, well-defined tools are much easier to reason about than one broad autonomous action.

I also gained a much deeper understanding of why concepts such as idempotency, immutable authorization, state revisions, proposal expiry, and server-side enforcement matter in agent-driven applications.

Another important lesson was that human-in-the-loop design should not mean simply adding an "Are you sure?" button.

The human should be reviewing a specific object, with enough information to understand what is being authorized, and the system should be able to prove that the executed action is the same action that was reviewed.

LoadGuard's 3D candidate view became an important part of that idea because the operator and the agent are effectively working around the same proposed state.

What's next for LoadGuard 3D

LoadGuard currently focuses on a controlled truck-loading scenario rather than pretending to be a full production fleet or warehouse platform.

It does not currently claim live IoT telemetry, GPS integration, computer vision, robotic loading, or autonomous physical execution.

That is intentional.

The current project focuses on demonstrating the core interaction model clearly:

structured WebMCP capabilities + deterministic planning + human-controlled execution.

A future version could connect this same authority model to real operational systems such as:

  • warehouse management systems
  • package scanners
  • live shipment events
  • fleet-management platforms
  • scheduling systems
  • inventory systems
  • additional logistics workflows

The deeper idea also extends beyond logistics.

Any application where an agent can perform useful preparation but where execution has financial, operational, security, or physical consequences could benefit from the same separation of responsibilities.

The long-term direction for LoadGuard is therefore not simply "better truck packing."

It is exploring a broader pattern for trustworthy operational agents:

Let the agent do the work it is good at.
Let the human retain consequential authority.
Let the application enforce the boundary between them.

Built With

Share this project:

Updates

Submission history