User Guide — Work-Order Agent Ecosystem

Who this is for

Operations and engineering users who want to (a) see how an inbound work order is processed automatically, and (b) understand when and why a human is pulled in.

0. Install (once)

npm install

For the external live services (a separate PostgreSQL server + the Go gRPC service), also start the containers and set the two env vars:

docker compose up -d --build
# PowerShell
$env:DATABASE_URL="postgres://forge:forge@127.0.0.1:5433/workorders"
$env:DISPATCH_GRPC_URL="127.0.0.1:50051"

Without those, the tools run in a self-contained in-process mode (PGlite + Node gRPC). All other knobs are environment-driven — see .env.example.

1. Run a batch of synthetic orders

node run.mjs --n 20

Each run boots a real PostgreSQL DB and a real gRPC dispatch service, then processes the batch through them.

Each order prints its category + confidence, priority, route, validation status, final action, and a human-readable reason. The batch summary shows the auto-dispatch / human-exception / rejected split and the human-in-the-loop rate.

2. Classify a single free-text order

node run.mjs --text "the breaker in the east hallway keeps tripping, urgent, location E1"

Try variations to see the safety behaviour:

• Drop the location → REJECTED (MISSING_LOCATION).
• Mention two trades ("thermostat and also the toilet") → HUMAN_EXCEPTION

(low confidence).

• Add "estimated cost $8,000" → HUMAN_EXCEPTION (OVER_COST_LIMIT).

3. Process your own orders from a file

Create orders.json:

[
  { "id": "WO-1", "rawText": "roof leak near the parapet, location N2", "location": "N2" },
  { "id": "WO-2", "rawText": "please repaint the lobby, low priority, location S1", "location": "S1" }
]

node run.mjs --file orders.json

3b. Run the live HTTP service

node server.mjs
curl -s localhost:8080/healthz
curl -s -X POST localhost:8080/work-orders -H "content-type: application/json" \
  -d "{\"rawText\":\"roof leak near the parapet, location N2\",\"location\":\"N2\"}"
curl -s localhost:8080/work-orders/<returned-id>

The order is classified, routed, validated, dispatched over real gRPC, and persisted to PostgreSQL; the GET returns the stored record plus its audit trail.

4. The live React console

Open public/console.html in any modern browser. Paste or pick a work order and watch the four agents run live (classify → route → validate → action). This is a client-side demonstration of the heuristics; the verified engine is the Node pipeline (see proof/LIMITATIONS.md).

5. Tuning policy

Validator thresholds (confidence floors, cost cap, duplicate window) and the routing tables are documented in specs/agent-validator.md and specs/routing-policy.md. After any change, run node verify.mjs.

Understanding the disposition