Safeguard Work-Order Agent Ecosystem

Overview

Safeguard Work-Order Agent Ecosystem

An AI agent ecosystem that processes received work orders end-to-end — classify → route → validate → action — so humans are needed only for genuine exceptions. Verified against external live services: a separate PostgreSQL server, a separate Go gRPC dispatch service, and a real HTTP ingest API. Shipped with a full IRS_AUDITOR proof package.

Honest scope. The infrastructure is real and external (verified over the
wire, including restart/reconnect). The remaining gap is the data: inbound
orders are synthetic, so accuracy is measured against a synthetic answer
key — not real Safeguard data. That is why the Proof Layer state is CERTIFIED
and not PRODUCTION_VALIDATED. See proof/LIMITATIONS.md
for the full seam list and the exact path to PRODUCTION_VALIDATED.

The four agents

Agent	Role	Source
Classifier	trade category + priority + field extraction, with confidence	`src/agents/classifier.mjs`
Router	queue, crew, vendor tier, region, SLA (env-configurable)	`src/agents/router.mjs`
Validator	safety boundary: VALID / NEEDS_REVIEW / REJECT	`src/agents/validator.mjs`
Actioner	auto-dispatch (real gRPC) vs. human exception, idempotent + audited	`src/agents/actioner.mjs`

Orchestrated by src/orchestrator.mjs. External infra: dispatch-service/ (Go gRPC), docker-compose.yml (Postgres + Go service), src/db/ (Postgres client), src/integrations/ (gRPC client + repository), proto/dispatch.proto.

Quick start (external live services)

cd delivery-package/work-order-agents
npm install
docker compose up -d --build      # PostgreSQL 16 (:5433) + Go gRPC service (:50051)

# PowerShell
$env:DATABASE_URL="postgres://forge:forge@127.0.0.1:5433/workorders"
$env:DISPATCH_GRPC_URL="127.0.0.1:50051"
node verify.mjs                   # 23 checks against external Postgres + Go gRPC
node server.mjs                   # HTTP API on :8080

Self-contained fallback (no Docker): node verify.mjs runs the same logic against in-process PGlite + a Node gRPC server (21 checks).

Verified results (external live stack, synthetic corpus, seed 42)

Metric	Value
Checks	23 / 23 PASS (external Postgres + Go gRPC + HTTP + restart/reconnect)
Infrastructure	external PostgreSQL 16 server + Go gRPC service (Docker)
Classification accuracy	98.87%
Exception recall / precision	1.0 / 0.974
False-auto-action rate	0.0%
Automatic-action rate	62.17% (human-in-the-loop → ~37.8%)
Persisted / audited	600 work orders, 600 audit rows, durable across DB restart

Reproduce everything: proof/REPRODUCE.md.

Configuration (environment)

DATABASE_URL, DISPATCH_GRPC_URL, MIN_CATEGORY_CONFIDENCE, MIN_PRIORITY_CONFIDENCE, MAX_AUTO_APPROVE_COST, DUPLICATE_WINDOW_MS, SLA_P1_HOURS/SLA_P2_HOURS/…, PORT, GRPC_PORT, DB_DIR. See .env.example and src/config.mjs.

What's in the box

src/ — agents, orchestrator, config, DB client, gRPC client, repository, HTTP app.
dispatch-service/ — the Go gRPC dispatch service (+ Dockerfile).
proto/dispatch.proto — the gRPC dispatch contract (shared by Node + Go).
docker-compose.yml — external PostgreSQL + Go service.
server.mjs — HTTP ingest service.
specs/, proof/, public/console.html.

Tie-in to existing systems

The actioner dispatches over a real gRPC wire to the Go service and persists to an external Postgres via a repository that also targets any Postgres through DATABASE_URL. Oracle would use the same interface via an Oracle adapter (not included). See run-deploy-instructions.md.