🤖 Agent Architecture V4 Manual

This is the definitive architecture document for the RABS Agent system (V4). It describes the core philosophy, agent taxonomy, network topology, tagging system, context model, tools registry, monitoring framework, database schema, admin dashboard, approval workflow, prime directives, and implementation roadmap.

1. Core Philosophy

The Agent Architecture V4 is built on a single foundational principle: Agents have Agency; the System retains Authority.

Agents are free to think, plan, reason, and propose — but they never hold keys, never execute unilaterally on critical paths, and every action is audited. This separation is enforced architecturally, not just by policy.

Air Gap

Every agent VM runs in complete isolation with NAT-only networking. Agents cannot reach the host network, the internet, or each other directly. All communication flows through a controlled API surface exposed by the RABS application on the host. There is no SSH, no shared filesystem, no back-channel.

Cognitive Loop

Every agent follows the same five-phase cognitive loop:

┌──────────────────────────────────────────────┐
│                                              │
│   Ingest  →  Decide  →  Execute  →  Review   │
│      ▲                                │      │
│      └────────── Learn ◄──────────────┘      │
│                                              │
└──────────────────────────────────────────────┘

Phase	Description
Ingest	Agent receives a task, message, or event from the RABS task queue or inbox. Context buckets and standing instructions are loaded.
Decide	Agent reasons about the input using its LLM, consults local memory (SQLite), and determines an action plan. An R-Tag (Reason Tag) is generated.
Execute	Agent calls tools via the Tools Broker. The broker validates permissions, checks V-Pol (Validation Policy), and routes the call. Critical tools enter the Approval Queue.
Review	Results are checked against expected outcomes. Alignment scoring occurs. Misalignments are logged and may trigger demotion.
Learn	Observations are written to context buckets. Local SQLite memory is updated. Relevance scores are recalculated. The cycle repeats.

2. Agent Types

RABS classifies agents into three types based on their execution environment and integration model.

Type 1 — RABS Native

Property	Value
Execution	Inline LLM calls within the RABS application process
Isolation	None — runs in the same Node.js process as the app
Use Cases	Quick classification, summarisation, field extraction, template generation
Cost Profile	Lowest — single API call per task
Examples	Inline GPT calls for message triage, document summarisation

Type 1 agents are lightweight. They do not maintain persistent memory, do not have their own VM, and do not participate in the full cognitive loop. They are fire-and-forget LLM calls wrapped in the RABS tool framework.

Type 2 — Sandboxed CLI

Property	Value
Execution	Dedicated VM with NAT-only networking
Isolation	Full OS-level isolation. No internet, no host LAN access.
Use Cases	Multi-step reasoning, research, document generation, data analysis
Cost Profile	Medium — persistent VM, multi-turn conversations
Examples	Henry (operations agent), Reggie (front-desk / reception agent)

Type 2 agents are the workhorses of the system. Each runs in its own VM with:

A local Agent Service (API server)
Local SQLite memory (agent_memory.db)
An inbox/outbox pattern for file exchange
Multi-step reasoning with chain-of-thought logging

Type 3 — External

Property	Value
Execution	Third-party service, webhook-based integration
Isolation	External to RABS infrastructure entirely
Use Cases	Real-time voice, video, workflow automation
Cost Profile	Variable — per-minute or per-event billing
Examples	LiveKit (real-time voice), Tavus (video), Zapier (workflow automation)

Type 3 agents are integrated via webhooks and API callbacks. RABS pushes events to them and receives results asynchronously. They do not have access to the Tools Broker directly — all interactions are mediated through adapter services.

3. Network Architecture

All agent infrastructure runs on host Lucas (192.168.77.6). Agent VMs use NAT-only networking and are accessible only through port-forwarded endpoints on the host loopback or LAN interface.

Port Mapping

Agent	Service	Host Binding	Guest Port	Notes
Henry	API	`127.0.0.1:18080`	`8080`	Loopback only — not LAN-accessible
Henry	Dashboard	`192.168.77.6:13000`	`3000`	LAN-accessible for admin UI
Reggie	API	`127.0.0.1:19090`	`9090`	Loopback only — not LAN-accessible
Reggie	Dashboard	`192.168.77.6:14000`	`4000`	LAN-accessible for admin UI

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│  LUCAS (Host)  192.168.77.6                                     │
│                                                                 │
│  ┌──────────────────────────────────────────────────┐          │
│  │  RABS Application                                 │          │
│  │  ├─ Tools Broker   (validates, routes, audits)    │          │
│  │  ├─ Task Queue     (pushes work to agents)        │          │
│  │  └─ Approval Queue (holds pending human reviews)  │          │
│  └──────────────────────────────────────────────────┘          │
│                        ▲ REST API                               │
│  ┌─────────────┐     │     ┌─────────────┐                     │
│  │  PostgreSQL  │◄────┤     │  PostgreSQL  │                    │
│  │  brainframe  │     │     │  brainframe  │                    │
│  │  schema      │     │     │  schema      │                    │
│  └─────────────┘     │     └─────────────┘                     │
│                        │                                        │
│  ┌─────────────────┐  │  ┌─────────────────┐                   │
│  │  Henry VM (NAT)  │  │  │  Reggie VM (NAT) │                  │
│  │  Agent Service   │──┘  │  Agent Service   │                  │
│  │  SQLite memory   │     │  SQLite memory   │                  │
│  │  inbox/outbox    │     │  inbox/outbox    │                  │
│  └─────────────────┘     └─────────────────┘                   │
└─────────────────────────────────────────────────────────────────┘

Communication Flow

RABS Application pushes a task to the agent's inbox via the host-forwarded API port.
The Agent Service inside the VM picks up the task, reasons about it, and calls tools back through the same REST API.
The Tools Broker on the RABS side validates the call against the tool registry, checks V-Pol, and either executes immediately or queues for approval.
Results flow back to the agent. Completed deliverables are placed in the agent's outbox for collection.

4. Tag Trinity (R-Tag, O-Tag, V-Pol)

Every agent decision is tagged with three identifiers that form the Tag Trinity. These tags provide full traceability from any action back to its origin, reasoning, and authority.

R-Tag (Reason Tag) — WHY

Property	Description
Purpose	Links to a specific entry in the `reason_log` table
Semantics	Explains WHY a decision was made
Mutability	Changes on each new decision or knock-on effect
Format	UUID reference to `brainframe.reason_log.id`

When an agent makes a decision, a new R-Tag is generated. If that decision triggers a knock-on (e.g., rescheduling a shift triggers a notification), the knock-on gets its own R-Tag — but inherits the original O-Tag.

O-Tag (Origin Tag) — THE SOURCE

Property	Description
Purpose	Identifies the actual message, event, or trigger that started the chain
Semantics	THE SOURCE — what actually happened
Mutability	Does NOT change during knock-on chains
Format	UUID reference to `brainframe.origin_registry.id`

The O-Tag is immutable within a causal chain. If a participant's email triggers a shift change which triggers a notification which triggers a billing adjustment — all four actions share the same O-Tag pointing back to that original email.

V-Pol (Validation Policy) — THE AUTHORITY

Property	Description
Purpose	Specifies the permission rules and validation constraints that governed the decision
Semantics	THE AUTHORITY — what rules apply
Mutability	Does NOT change during knock-on chains
Format	UUID reference to `brainframe.validation_policies.id`

V-Pol defines what an agent is allowed to do, under what conditions, and with what level of human oversight. It is set at the start of a chain and inherited by all downstream actions.

Tag Trinity in Action

Email arrives from participant
  └─ O-Tag: OT-4821 (the email)
     └─ R-Tag: RT-9001 (reason: "participant requested schedule change")
        V-Pol: VP-12 (scheduling_write, review mode)
        Action: Update shift in roster
           └─ R-Tag: RT-9002 (reason: "knock-on: notify affected staff")
              O-Tag: OT-4821 (same origin — the email)
              V-Pol: VP-12 (same policy)
              Action: Send notification
                 └─ R-Tag: RT-9003 (reason: "knock-on: update billing forecast")
                    O-Tag: OT-4821 (same origin — the email)
                    V-Pol: VP-12 (same policy)
                    Action: Adjust billing line item

5. Context Buckets

Context Buckets are the 20 knowledge domains that partition all organisational information. Every observation, pattern, and tool call is classified into one or more buckets. Buckets drive relevance scoring, tool routing, and agent specialisation.

The 20 Domains

#	Bucket	Scope
1	`billing_finance`	Invoicing, payments, NDIS claims, Xero sync, financial reporting
2	`programs_services`	Program definitions, service types, capacity, enrolments
3	`comms_staff`	Internal staff communications, announcements, memos
4	`comms_participant_carer`	Participant and carer messaging, check-ins, updates
5	`comms_admin_exec`	Executive and admin communications, board updates
6	`comms_public_other`	Public-facing comms, external enquiries, general inbound
7	`transportation`	Vehicle bookings, driver schedules, route planning
8	`facilities_assets`	Building maintenance, equipment, asset registers
9	`rostering_scheduling`	Shift creation, roster publication, availability, swaps
10	`payroll_alliance`	Pay runs, Alliance Payroll integration, leave, allowances
11	`staff_performance`	KPIs, reviews, coaching notes, performance journals
12	`health_medical_wellbeing`	Medical records, wellbeing checks, allied health
13	`compliance_regulatory`	NDIS audits, quality indicators, policy compliance
14	`feedback_audits`	Internal audits, feedback forms, improvement actions
15	`data_reporting`	Dashboards, analytics, scheduled reports, exports
16	`pr_socials`	Social media, public relations, marketing content
17	`incidents_safety`	Incident reports, WHS, hazard registers, investigations
18	`training_development`	Staff training records, certifications, CPD, onboarding
19	`participant_goals`	NDIS goals, progress notes, outcome tracking
20	`vendor_suppliers`	Supplier contracts, procurement, vendor management

Bucket Storage

Each bucket entry in brainframe.context_buckets contains:

Field	Type	Description
`bucket`	`text`	One of the 20 domain names
`pattern_type`	`text`	Classification of the observation (e.g., `preference`, `recurring_issue`, `capacity_trend`)
`entity`	`text`	The subject (staff name, participant, program, etc.)
`observation`	`text`	The actual insight or pattern
`scoring`	`jsonb`	Relevance scoring data (severity, frequency, decay, etc.)
`decay`	`numeric`	Current decay multiplier (starts at 1.0)
`vector`	`vector(768)`	Embedding for semantic search

6. Relevance Scoring

Relevance scoring determines which observations and patterns surface to agents during the Decide phase. Stale information decays; urgent, recurring issues rise to the top.

Scoring Formula

current_score = (Severity × Frequency) × Decay × Repeatable × FamilyBoost

Factor	Range	Description
Severity	1–5	How critical the observation is. 1 = trivial, 5 = safety/compliance critical.
Frequency	1+	How many times this pattern has been observed. Increments on each recurrence.
Decay	0.0–1.0	Time-based decay. Starts at 1.0, reduced by 2% daily.
Repeatable	0.5–1.5	Modifier for whether this is a one-off or structural pattern.
FamilyBoost	1.0–2.0	Boost when multiple related observations exist in the same bucket for the same entity.

Decay Mechanics

A nightly job runs at 02:00 AEST and applies 2% decay to all context bucket entries.
Decay formula per night: new_decay = current_decay × 0.98
After 30 days of no reinforcement, an observation's decay factor reaches ~0.545 (roughly half its original score).
After 90 days: ~0.163. After 180 days: ~0.027.
Observations are not deleted — they simply become irrelevant through scoring. This preserves the audit trail.

Score Reinforcement

When an observation is seen again (same bucket, same entity, same pattern_type), the system:

Increments frequency by 1.
Resets decay to 1.0.
Recalculates current_score.

This means recurring issues naturally stay at the top while one-off observations fade.

7. Tools Registry

The Tools Registry is the central catalogue of every action an agent can perform. Every tool call flows through the Tools Broker, which validates the request against the registry before execution.

Schema Key Fields

Field	Type	Description
`tool_id`	`text`	Unique identifier (e.g., `roster.shift.create`, `comms.email.send`)
`agent_access`	`text[]`	Which agents may invoke this tool (e.g., `['henry', 'reggie']`)
`role_requirements`	`text[]`	Which RABS user roles are needed for the tool's context
`risk_level`	`enum`	`read`, `write`, or `critical`
`execution_mode`	`enum`	`auto` (immediate), `review` (approval queue), `disabled`
`context_bucket`	`text`	Primary context bucket this tool operates in
`monitoring_level`	`integer`	Current monitoring level (0–4) for this tool
`alignment_score_90d`	`numeric`	Rolling 90-day alignment score
`validation_mode`	`enum`	`monitor` (log only), `intercept` (block + review), `strict` (block + require approval)
`data_class`	`enum`	`logistics`, `clinical`, `finance`, `pii`
`handler_type`	`text`	Execution backend (e.g., `sql`, `api`, `function`, `script`)
`handler_config`	`jsonb`	Handler-specific configuration
`input_schema`	`jsonb`	JSON Schema for tool input validation
`output_schema`	`jsonb`	JSON Schema for expected output

Tool Categories

Category	Scope	Examples
`operations`	Day-to-day operational tools	Shift management, transport booking, facility checks
`comms`	Communication tools	Email send, SMS, notification push, message classification
`hr`	Human resources tools	KPI updates, leave requests, contract generation
`finance`	Financial tools	Invoice creation, payment reconciliation, NDIS claims
`data`	Data and reporting tools	Report generation, analytics queries, export tools
`system`	System administration tools	Cache clear, job triggers, config updates

Risk Levels and Execution

Risk Level	Default Execution Mode	Examples
`read`	`auto`	Fetch roster, list participants, query reports
`write`	`review`	Create shift, send email, update KPI score
`critical`	`review`	Delete records, modify billing, access PII, change permissions

8. Reggie Modes

Reggie (the reception/front-desk agent) operates in three distinct modes, each with different capabilities, cost profiles, and use cases.

Normal Reggie

Property	Value
Model	`gpt-4o-mini`
Tools	Read-only tools via the Tools Broker
Cost	~$0.01 per query
Use Cases	Answering common questions, looking up schedules, checking participant info
Execution	Synchronous, single-turn

Normal Reggie is the default mode. It handles the vast majority of reception queries — schedule lookups, participant enquiries, basic triage. It cannot modify data.

Super Reggie

Property	Value
Model	`gpt-4o` / `o1` (selectable)
Tools	Full sandboxed VM toolset, read replica database access
Cost	~$0.10 per query
Use Cases	Complex research, multi-step analysis, document drafting, data cross-referencing
Execution	Multi-turn reasoning within the VM sandbox

Super Reggie is activated when a query requires deeper reasoning or write operations. It runs inside the full VM sandbox with access to a read replica of the database and the complete tools registry (subject to V-Pol).

External Reggie

Property	Value
Model	OpenAI Realtime API via LiveKit
Tools	Tool webhooks (bridged through RABS)
Cost	~$0.06 per minute
Use Cases	Live phone calls, voice-based reception, real-time conversation
Execution	Streaming, real-time, voice-in/voice-out

External Reggie handles live voice interactions. It uses the LiveKit platform to bridge the OpenAI Realtime API with telephony. Tool calls during voice sessions are routed through webhooks back to the RABS Tools Broker.

Mode Selection Flow

Incoming Query
     │
     ├─ Voice call? ──────────► External Reggie (LiveKit)
     │
     ├─ Simple lookup? ───────► Normal Reggie (gpt-4o-mini)
     │
     └─ Complex / write? ────► Super Reggie (gpt-4o / o1)

9. Monitoring Levels

The monitoring framework implements a trust-based graduation system. Agents and tools start at Level 0 (no trust) and can graduate to Level 4 (full autonomy) based on sustained alignment.

Level Definitions

Level	Name	Alignment Threshold	Human Involvement
0	Review-All	Default (new tools/agents)	Every action requires human approval before execution
1	Pre-Exec Sampling	alignment >= 0.70	Random sample of actions reviewed before execution
2	Post-Exec Review	alignment >= 0.80	Actions execute immediately; reviewed after the fact
3	Spot-Check	alignment >= 0.90	Periodic random audits only
4	Autonomous	alignment >= 0.95	No routine human review; exceptions only

Graduation Rules

To graduate from Level N to Level N+1, a tool must:

Maintain the threshold alignment score for 30 consecutive days.
Record zero high-priority misalignments during that 30-day window.
Have processed a minimum volume of actions (prevents graduation on tiny sample sizes).

Graduation is automatic — the nightly alignment job evaluates all tools and promotes eligible ones.

Demotion Rules

Demotion is immediate and automatic when any of the following conditions are met:

Trigger	Action
5+ misalignments in 24 hours	Demote by 1 level
Alignment score drops below current level's threshold	Demote to the highest level the score still qualifies for
Any critical misalignment (safety, PII, compliance)	Immediate demotion to Level 0

Alignment Scoring

Alignment is calculated as a rolling 90-day weighted average:

alignment_score_90d = weighted_avg(
    recent_actions.map(action => action.alignment_rating),
    weight = recency_bias  // more recent actions weighted higher
)

Each tool call in the brainframe.tool_calls audit log receives an alignment rating (0.0–1.0) based on:

Did the action match the stated intent?
Was the output within expected parameters?
Did any human reviewer flag issues?
Were prime directives respected?

10. Database Schema (brainframe)

All agent-related tables reside in the brainframe schema within the main PostgreSQL database (rabsdb).

Core Tables

Table	Purpose	Key Fields
`agents`	Agent definitions and configuration	`agent_id`, `name`, `type`, `status`, `config`, `monitoring_level`
`tools`	Tool registry (see Section 7)	`tool_id`, `agent_access[]`, `risk_level`, `execution_mode`, `alignment_score_90d`
`validation_policies`	V-Pol definitions	`vpol_id`, `name`, `rules`, `context_bucket`, `enforcement_mode`
`reason_log`	Decision ledger — every agent decision is recorded here	`id`, `r_tag`, `o_tag`, `vpol_id`, `chain_id`, `thought`, `risk`, `alignment`, `vector(768)`
`origin_registry`	O-Tag source registry	`id`, `origin_type`, `source_ref`, `timestamp`, `metadata`
`context_buckets`	Patterns and observations (see Section 5)	`bucket`, `pattern_type`, `entity`, `observation`, `scoring`, `decay`, `vector(768)`
`reason_edges`	Links R-Tags to entities for graph traversal	`reason_id`, `entity_type`, `entity_id`, `relationship`
`agent_tasks`	Work queue for agent assignments	`task_id`, `agent_id`, `status`, `priority`, `payload`, `created_at`, `started_at`, `completed_at`
`approval_queue`	Human-in-the-loop review items	`id`, `tool_id`, `agent_id`, `arguments`, `reason`, `summary`, `risk_level`, `confidence`, `tags`, `status`, `timeout_at`
`tool_calls`	Audit log of every tool invocation	`id`, `tool_id`, `agent_id`, `r_tag`, `input`, `output`, `alignment_rating`, `duration_ms`, `timestamp`
`agent_notes`	Standing instructions and persistent notes for agents	`id`, `agent_id`, `note_type`, `content`, `priority`, `active`

Entity Relationship Overview

agents ──────────┐
                 │ 1:N
                 ▼
           agent_tasks ◄──── approval_queue
                 │                  │
                 │ triggers         │ references
                 ▼                  ▼
           tool_calls ────────► tools
                 │                  │
                 │ tagged with      │ governed by
                 ▼                  ▼
           reason_log ◄──── validation_policies
                 │
                 │ links to
                 ▼
           reason_edges ────► (any entity in RABS)
                 │
                 │ originates from
                 ▼
           origin_registry

           context_buckets (independent, referenced by bucket name)
           agent_notes (per-agent standing instructions)

11. Dual Database Strategy

RABS employs a dual-database strategy that separates authoritative system state from agent-local working memory.

RABS Main DB (PostgreSQL)

Property	Value
Engine	PostgreSQL 16
Database	`rabsdb`
Schema	`brainframe` (agent tables), `public` (RABS core), `hr` (HR/KPI)
Role	Authority — single source of truth for all decisions, tools, policies, and audit trails
Access	Agents access via Tools Broker only (no direct DB connections from VMs)

Agent Local SQLite (`agent_memory.db`)

Each Type 2 agent VM contains a local SQLite database for working memory. This database is not authoritative — it is a scratch pad that helps the agent maintain conversational context and personal preferences between interactions.

Table	Purpose	Notes
`conversations`	Recent conversation history and context	Rolling window, pruned by age
`self`	Agent's encrypted internal journal	Reflections, strategy notes, self-assessments. Encrypted at rest.
`user_preferences`	Learned preferences about users the agent interacts with	Communication style, timezone, preferred name, etc.

Why Dual DB?

PostgreSQL (Authority)              SQLite (Working Memory)
─────────────────────              ──────────────────────
• Decisions are final              • Drafts and scratch work
• Audit trail is immutable         • Can be wiped and rebuilt
• Shared across all agents         • Private to each agent
• Accessible via Tools Broker      • Direct file access in VM
• Backed up and replicated         • Ephemeral by design

12. Admin Dashboard (Klaus-Inspired Kanban)

The admin dashboard provides real-time visibility into agent operations. Its design is inspired by the Klaus quality assurance platform — a clean Kanban-based interface with agent-specific panels.

Layout

┌──────────────────────────────────────────────────────────────────┐
│  [Agent Selector: Henry ▾]                    [Status: Active]   │
├───────────────┬───────────────┬──────────────┬───────────────────┤
│   TO DO       │  IN PROGRESS  │   REVIEW     │     DONE          │
│               │               │              │                   │
│  ┌─────────┐  │  ┌─────────┐  │  ┌────────┐  │  ┌─────────────┐  │
│  │ Task 12 │  │  │ Task 9  │  │  │ Task 7 │  │  │ Task 3      │  │
│  │ Roster  │  │  │ Email   │  │  │ KPI    │  │  │ Shift swap  │  │
│  │ update  │  │  │ draft   │  │  │ review │  │  │ completed   │  │
│  └─────────┘  │  └─────────┘  │  └────────┘  │  └─────────────┘  │
│  ┌─────────┐  │               │              │  ┌─────────────┐  │
│  │ Task 14 │  │               │              │  │ Task 1      │  │
│  │ Vehicle │  │               │              │  │ Report sent │  │
│  │ check   │  │               │              │  └─────────────┘  │
│  └─────────┘  │               │              │                   │
├───────────────┴───────────────┴──────────────┴───────────────────┤
│  DELIVERABLES (Outbox)        │  NOTES (Standing Instructions)   │
│  ├─ report_march_2026.pdf     │  • Always CC manager on emails   │
│  ├─ roster_week12.xlsx        │  • Use formal tone for external  │
│  └─ incident_summary.docx    │  • Flag any NDIS budget > 80%    │
├───────────────────────────────┴──────────────────────────────────┤
│  ACTION LOG (Live Stream)                                        │
│  14:23:01  [Henry] tool_call: roster.shift.read → OK (12ms)     │
│  14:23:03  [Henry] tool_call: comms.email.draft → REVIEW (45ms) │
│  14:23:15  [Admin] approval: comms.email.draft → APPROVED        │
│  14:23:16  [Henry] tool_call: comms.email.send → OK (230ms)     │
└──────────────────────────────────────────────────────────────────┘

Dashboard Components

Component	Description
Agent Selector	Dropdown to switch between agents (Henry, Reggie, etc.)
Status Card	Current agent status (Active, Idle, Paused, Error), uptime, task count, alignment score
4-Column Kanban	To Do / In Progress / Review / Done columns showing current task pipeline
Deliverables	Files in the agent's outbox ready for download or distribution
Notes Panel	Standing instructions from `agent_notes` — persistent directives the agent follows
Action Log	Live-streaming log of tool calls, approvals, and state changes (SSE-powered)

13. Approval Queue

The Approval Queue is the human-in-the-loop mechanism. When an agent calls a tool with execution_mode = 'review' or validation_mode = 'intercept'/'strict', the call is paused and an entry is created in the approval queue.

Queue Entry Schema

Field	Type	Description
`id`	`uuid`	Unique approval request ID
`tool_id`	`text`	The tool being invoked
`agent_id`	`text`	Which agent made the request
`arguments`	`jsonb`	The full arguments the agent wants to pass to the tool
`reason`	`text`	Agent's stated reason for the action (from R-Tag)
`summary`	`text`	Human-readable summary of what will happen if approved
`risk_level`	`enum`	`read`, `write`, or `critical`
`confidence`	`numeric`	Agent's self-assessed confidence (0.0–1.0)
`tags`	`text[]`	Context tags (bucket, entity, etc.)
`status`	`enum`	`pending`, `approved`, `rejected`, `modified`, `escalated`, `expired`
`timeout_at`	`timestamp`	When the request expires (default: 30 minutes from creation)

Admin Actions

Action	Effect
Approve	Tool call executes with the original arguments. Positive alignment signal recorded.
Reject	Tool call is cancelled. Agent is notified with rejection reason. Negative alignment signal recorded.
Modify	Admin edits the arguments before approving. The modified version executes. Alignment is neutral (agent's intent was right, parameters were wrong).
Escalate	Request is bumped to a higher authority (e.g., from team lead to director). Timeout resets.

Timeout Behaviour

Default timeout: 30 minutes.
When a request expires without action, it is marked expired and the agent is notified.
Expired requests count as neutral for alignment scoring (not the agent's fault).
The agent may re-submit with updated reasoning if the task is still relevant.

14. Prime Directives

Prime Directives are non-negotiable rules that override all other agent behaviour. They are enforced at multiple layers to ensure defence-in-depth.

Active Directives

Directive	Priority	Scope
`PRIVACY_NO_PII`	100	No personally identifiable information may be included in agent outputs, logs visible to other agents, or external communications without explicit consent flags.
`NDIS_COMPLIANCE`	95	All actions affecting NDIS participants, billing, or reporting must comply with current NDIS Practice Standards and Price Guide rules.
`SAFETY_FIRST`	100	Any indication of immediate risk to safety (participant, staff, or public) triggers an immediate escalation to Level 0 monitoring and human notification.

Enforcement Layers

Prime Directives are enforced at four distinct points in the agent pipeline:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   LAYER 1   │    │   LAYER 2   │    │   LAYER 3   │    │   LAYER 4   │
│   Prompt    │───►│  Decision   │───►│  Alignment  │───►│  Outbound   │
│  Injection  │    │   Filter    │    │   Review    │    │ PII Filter  │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

Layer	Name	Mechanism
Layer 1	Prompt Injection	Directives are injected into every agent system prompt. The agent is instructed to self-check against them.
Layer 2	Decision Filter	Before any tool call is routed, the Tools Broker checks the action against directive rules programmatically.
Layer 3	Alignment Review	Post-execution, the alignment scorer checks whether the action violated any directives. Violations trigger immediate demotion.
Layer 4	Outbound PII Filter	All agent-generated text destined for external channels passes through a PII detection filter. Matches are redacted and flagged.

15. Implementation Roadmap

The V4 architecture is delivered in five phases, each building on the previous.

Phase 1 — Foundation

Deliverable	Description
`brainframe` schema	Create all tables in PostgreSQL: `agents`, `tools`, `validation_policies`, `reason_log`, `origin_registry`, `context_buckets`, `reason_edges`, `agent_tasks`, `approval_queue`, `tool_calls`, `agent_notes`
Tools admin UI	CRUD interface for managing the tools registry — add, edit, disable tools
Seed data	Initial tool definitions, validation policies, and context bucket configurations

Phase 2 — Dashboard

Deliverable	Description
Agent status cards	Real-time agent status display (active, idle, error, uptime)
Kanban board	4-column task board (To Do / In Progress / Review / Done)
Action log panel	Scrollable log of recent tool calls and state changes
Notes panel	View and edit standing instructions per agent
Deliverables panel	File browser for agent outbox contents

Phase 3 — Backend

Deliverable	Description
Tools Broker	Central routing service: validates tool calls against registry, checks V-Pol, routes to handler or approval queue
Bucket Checker	Context bucket classifier: assigns incoming events/observations to the correct bucket(s)
Validation Engine	V-Pol enforcement: evaluates validation policies against tool call context and agent permissions
Approval Queue API	REST endpoints for queue management: list, approve, reject, modify, escalate

Phase 4 — Agent Integration

Deliverable	Description
VM provisioning	Henry and Reggie VMs configured with NAT-only networking, port forwarding, Agent Service installed
Agent Service	Node.js service inside each VM: REST API, SQLite memory, inbox/outbox, cognitive loop runner
Tool calling bridge	Agent-side SDK for calling tools through the broker: authentication, request signing, response parsing
Local SQLite setup	`agent_memory.db` with `conversations`, `self` (encrypted), and `user_preferences` tables

Phase 5 — Polish

Deliverable	Description
SSE live streaming	Server-Sent Events for real-time action log and status updates in the dashboard
Decay nightly job	Cron job: apply 2% decay to all context bucket entries, recalculate scores
Alignment scorer	Post-execution alignment evaluation: score each tool call, update 90-day rolling averages
Graduation engine	Nightly evaluation: promote/demote tools based on alignment thresholds and 30-day windows
PII outbound filter	Layer 4 enforcement: scan all outbound agent text for PII patterns, redact and flag

Phase Summary

Phase 1: Foundation ──► Phase 2: Dashboard ──► Phase 3: Backend
                                                      │
                                                      ▼
                        Phase 5: Polish ◄──── Phase 4: Integration

Appendix A — Glossary

Term	Definition
R-Tag	Reason Tag — links an action to its reasoning in the `reason_log`
O-Tag	Origin Tag — immutable reference to the triggering event in `origin_registry`
V-Pol	Validation Policy — the rule set governing what an agent may do
Tag Trinity	The combination of R-Tag + O-Tag + V-Pol that tags every agent decision
Tools Broker	The central routing and validation layer for all tool calls
Context Bucket	One of 20 knowledge domains that partition organisational information
Alignment Score	Rolling 90-day measure of how well an agent/tool performs vs expectations
Monitoring Level	Trust tier (0–4) determining the degree of human oversight
Cognitive Loop	The 5-phase cycle: Ingest → Decide → Execute → Review → Learn
Air Gap	Architecture principle: agents run in isolated VMs with no direct network access
Prime Directive	Non-negotiable rule that overrides all other agent behaviour
Graduation	Automatic promotion to a higher monitoring level based on sustained alignment
Demotion	Automatic reduction in monitoring level due to misalignment
brainframe	The PostgreSQL schema containing all agent-related tables

Appendix B — Quick Reference Card

AGENT ARCHITECTURE V4 — QUICK REFERENCE
════════════════════════════════════════

Philosophy:   Agents have Agency, System has Authority
Air Gap:      NAT-only VMs, no direct network access
Loop:         Ingest → Decide → Execute → Review → Learn

Types:        T1 = Native (inline LLM)
              T2 = Sandboxed (VM, Henry/Reggie)
              T3 = External (LiveKit/Tavus/Zapier)

Tags:         R-Tag = WHY (changes per decision)
              O-Tag = SOURCE (immutable in chain)
              V-Pol = AUTHORITY (immutable in chain)

Buckets:      20 domains, scored by relevance, 2% daily decay

Risk:         read → write → critical
Monitoring:   L0 (review-all) → L4 (autonomous)
Graduation:   30 days at threshold + zero high-priority misalignments
Demotion:     5+ misalignments/24h OR score drop OR critical violation

Reggie:       Normal ($0.01) | Super ($0.10) | External ($0.06/min)

Directives:   PRIVACY_NO_PII (100) | SAFETY_FIRST (100) | NDIS_COMPLIANCE (95)

Database:     PostgreSQL brainframe schema (authority)
              + SQLite agent_memory.db (working memory)

1. Core Philosophy​

Air Gap​

Cognitive Loop​

2. Agent Types​

Type 1 — RABS Native​

Type 2 — Sandboxed CLI​

Type 3 — External​

3. Network Architecture​

Port Mapping​

Architecture Diagram​

Communication Flow​

4. Tag Trinity (R-Tag, O-Tag, V-Pol)​

R-Tag (Reason Tag) — WHY​

O-Tag (Origin Tag) — THE SOURCE​

V-Pol (Validation Policy) — THE AUTHORITY​

Tag Trinity in Action​

5. Context Buckets​

The 20 Domains​

Bucket Storage​

6. Relevance Scoring​

Scoring Formula​

Decay Mechanics​

Score Reinforcement​

7. Tools Registry​

Schema Key Fields​

Tool Categories​

Risk Levels and Execution​

8. Reggie Modes​

Normal Reggie​

Super Reggie​

External Reggie​

Mode Selection Flow​

9. Monitoring Levels​

Level Definitions​

Graduation Rules​

Demotion Rules​

Alignment Scoring​

10. Database Schema (brainframe)​

Core Tables​

Entity Relationship Overview​

11. Dual Database Strategy​

RABS Main DB (PostgreSQL)​

Agent Local SQLite (agent_memory.db)​

Why Dual DB?​

12. Admin Dashboard (Klaus-Inspired Kanban)​

Layout​

Dashboard Components​

13. Approval Queue​

Queue Entry Schema​

Admin Actions​

Timeout Behaviour​

14. Prime Directives​

Active Directives​

Enforcement Layers​

15. Implementation Roadmap​

Phase 1 — Foundation​

Phase 2 — Dashboard​

Phase 3 — Backend​

Phase 4 — Agent Integration​

Phase 5 — Polish​

Phase Summary​

Appendix A — Glossary​

Appendix B — Quick Reference Card​