Next Digitwin OPC Agent Prototype

This directory contains the phase-2 Agent Skills prototype for Next Digitwin. It is intentionally isolated from the production application: it does not modify backend/, frontend/, Prisma schema, database migrations, MQTT ingestion, or UI code.

Purpose

The goal is to prove that Next Digitwin's custom Agent can run valuable industrial digital-twin workflows through explicit Skills:

user query
-> intent routing
-> fixed Skill workflow
-> local demo data lookup
-> AgentResponse / SceneAction output
-> contract validation
-> audit chain generation

This prototype validates the Agent capability model before migrating it into the real NestJS backend.

Directory Structure

opc/
  skills/
    locate-asset/
    highlight-anomalies/
    explain-status/
    query-trend/
    count-events/
    replay-review/
    line-overview/
    audit-trace/
  agent-runtime/
    package.json
    src/
      audit.mjs
      contracts.mjs
      demo.mjs
      eval.mjs
      fixtures.mjs
      repository.mjs
      runtime.mjs
      skill-router.mjs
      skills.mjs

Skills

Each folder under opc/skills contains a SKILL.md file. These files define the Agent capability contract:

• purpose
• trigger examples
• inputs
• required data
• deterministic workflow
• output contract
• rules
• failure modes
• eval expectations

The Skill markdown files are specifications. They do not execute by themselves.

Agent Runtime

opc/agent-runtime is a lightweight runnable prototype that implements the Skill workflows with local fixtures.

It validates:

• locate_asset: asset lookup, camera focus, highlight, details panel action
• highlight_anomalies: active event lookup and batch scene highlighting
• query_trend: point resolution and trend_chart widget output
• count_events: event counting and event_table widget output
• explain_status: point/event/document references and evidence-backed explanation
• replay_review: event-to-snapshot replay jump with set_replay_time
• line_overview: line-level risk summary
• audit_trace: 6-step audit chain reconstruction

It also validates shared constraints:

• frontend actions are only expressed as SceneAction
• responses use AgentResponse
• widgets use known contracts
• invalid scene action targets are dropped
• every execution writes the 6 required audit steps

Run

From this directory:

cd agent-runtime
node src/demo.mjs
node src/eval.mjs

Or from the repository root:

node ./agent-runtime/src/demo.mjs
node ./agent-runtime/src/eval.mjs

Expected eval result:

Summary: 7/7 passed

Some local shells may print unrelated environment warnings before the Node output. The useful signal is whether the demo runs and the eval summary passes.

What This Prototype Does Not Validate

This is not the production system. It does not validate:

• real LLM generateObject() behavior
• Prisma queries or database schema
• TimescaleDB performance
• pgvector retrieval quality
• MQTT ingestion
• WebSocket delivery
• frontend 3D rendering
• real Replay UI state management

Those belong to production integration under backend/ and frontend/.

The production implementation must continue to follow the project constraints:

• no ReAct
• no LLM tool calling for tool selection
• fixed switch-case routing by intent
• first-layer Skills use deterministic template responses
• evidence-dependent Skills must refuse deterministic conclusions when references are empty
• every intent/tool/action path must be auditable
• SceneAction must be validated before reaching the frontend