Type 2 Wiring & Operations Manual

Status: Active Version: 1.0 Last Updated: 2026-04-18

Overview

This document describes the complete wiring between RABS and the Type 2 agents (Reggie and Henry), covering the SMS pipeline, admin chat integration, memory system, hybrid broker model, workspace synchronisation, and operational procedures. It was written following the initial live deployment and testing on 2026-04-18.

For architectural rationale, see Hybrid Broker Architecture. For session schema, see Type2 Agent Session Architecture.

1. System Topology

┌──────────────────────────────────────────────────────────────┐
│  RABS Backend (192.168.77.6:3009)                            │
│                                                              │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
│  │ sms.js      │  │ agent-chat.js│  │ memory.js           │ │
│  │ (webhook)   │  │ (socket.io)  │  │ /api/v1/memory/*    │ │
│  └──────┬──────┘  └──────┬───────┘  └─────────────────────┘ │
│         │                │                                   │
│  ┌──────▼──────────────▼─────────┐                           │
│  │ sms-type2-handler.js          │                           │
│  │ - classifies caller           │                           │
│  │ - resolves identity           │                           │
│  │ - builds prompt (DB memory)   │                           │
│  │ - fires webhook to VM         │                           │
│  │ - multi-stage SMS notifs      │                           │
│  └──────────────┬────────────────┘                           │
│                 │                                            │
│  ┌──────────────▼────────────────┐                           │
│  │ type2-session.js              │                           │
│  │ - identity resolution         │                           │
│  │ - session management          │                           │
│  │ - prompt construction         │                           │
│  │ - auto memory logging         │                           │
│  └───────────────────────────────┘                           │
│                                                              │
│  ┌───────────────────────────────┐                           │
│  │ agent-governance.js           │                           │
│  │ - response-time logging       │                           │
│  │ - policy enforcement (future) │                           │
│  └───────────────────────────────┘                           │
└──────────────────────┬───────────────────────────────────────┘
                       │ HTTPS webhook
                       ▼
┌──────────────────────────────────────────────────────────────┐
│  Agent VMs                                                   │
│  ┌────────────────────┐  ┌────────────────────┐              │
│  │ Reggie VM (.17)    │  │ Henry VM (.16)     │              │
│  │ OC runner :19191   │  │ OC runner :18181   │              │
│  │ FD runner :19091   │  │ FD runner :18081   │              │
│  │                    │  │                    │              │
│  │ Reads: coreMEM     │  │ Reads: coreMEM     │              │
│  │ Reads: .env        │  │ Reads: .env        │              │
│  │ Access: DB (r/o)   │  │ Access: DB (r/o)   │              │
│  │ Access: RABS API   │  │ Access: RABS API   │              │
│  │ Access: repo clone │  │ Access: repo clone │              │
│  └────────────────────┘  └────────────────────┘              │
│                                                              │
│  Shared: /mnt/storage_agents/ (GoodSync to RABS host)       │
└──────────────────────────────────────────────────────────────┘

2. SMS Pipeline

Message Flow

Inbound SMS arrives at Twilio, forwarded to POST /api/v1/sms/webhook
sms.js validates Twilio signature, logs to comms.sms_messages, checks for keywords (STOP, START, NOCONTRACT, YES ###)
If no keyword match, fires handleIncomingSmsType2() in the background (does not await -- Twilio requires a response within 15 seconds or it retries)
sms-type2-handler.js takes over:
- Classifies the caller via inbound-classifier.js (staff/participant/external/unknown)
- Resolves identity to canonical person_id (YP3000 UUID)
- Gets or creates a Type 2 session
- Registers the request as in-flight (prevents duplicate processing)
- Builds prompt with DB memory context
- Fires webhook to agent VM runner
- Manages multi-stage SMS notifications while agent works
Agent responds, handler sends SMS reply via Twilio and logs everywhere

Multi-Stage SMS Notifications

Users don't see reasoning steps like admin chat users do. Instead, the handler sends timed notifications:

Delay	What the user receives	Purpose
2 seconds	💭 (thought bubble emoji)	Immediate acknowledgement -- message received
45 seconds	"Hey {name}, just working on that for you. I'll text back shortly. - Reggie"	First status update
2 min 15s	"Still on it {name}, this one's taking a bit of digging"	Periodic follow-up
Every 90s after	Rotating follow-up messages with personality	Keeps user informed
15 min (max)	Graceful failure with admin phone number	Safety net -- something is genuinely broken

All timers are cleared when the agent responds. If the agent responds in 10 seconds, the user only sees the 💭 and then the answer.

Follow-Up Message Handling

If a user sends another SMS while one is processing:

In-flight tracking detects the active request
User receives: "I'm still working on your earlier message -- I'll check this too and get back to you when I'm done!"
The follow-up is logged to the session
When the first request completes, queued follow-ups are processed as a new request with context from the previous exchange

Error Handling

If the webhook times out (15 min), the user receives a graceful British failure message with the admin phone number as fallback
Responses are logged to the database BEFORE attempting SMS delivery, so admin chat always shows the response even if Twilio fails
SMS delivery retries once with a 2-second delay on failure

3. Admin Chat Integration

How It Works

Admin chat uses Socket.IO for real-time communication. When a user sends a message via the admin dashboard:

agent-chat.js receives the message via socket
Resolves identity, gets/creates session
Builds prompt with DB memory context
Fires webhook to agent VM runner
Streams progress updates back via Socket.IO as the agent works
Delivers final response when agent completes

Timeouts

Setting	Reggie	Henry FD
Foreground timeout	2 min	15 min
Max runtime	15 min	30 min

The foreground timeout controls when the UI switches from "waiting with spinner" to "working in background, we'll notify you." The agent keeps working either way. Max runtime is a safety net, not a performance target.

Cross-Channel Visibility

Because identity is unified via person_id, SMS conversations appear in the admin chat interface. An admin can see what Reggie discussed with a staff member over SMS. This is by design -- the same person has one unified session regardless of channel.

4. Memory System

Architecture

Memory is entirely database-backed in the brainframe schema. No disk-based memory.

Table	Purpose	Written by
`memory_events`	Raw observations and interactions	`logMessage()` in type2-session.js (automatic)
`memory_indexes`	Fast-lookup preferences, facts, key observations	`/api/v1/memory/observe` (agent-initiated)
`memory_summaries`	Cumulative and weekly summaries	Nightly pipeline (not yet built)

Memory API

Agents access memory via the RABS API at http://192.168.77.6:3009/api/v1/memory/:

Endpoint	Method	Purpose
`/memory/recall`	GET	Retrieve summaries and context for a person
`/memory/search`	GET	Search indexed memories by keyword
`/memory/observe`	POST	Save a new observation (preference, fact, finding)
`/memory/feedback`	POST	Record feedback on a memory (reinforce or correct)

Prompt Injection

The buildPrompt() function in type2-session.js automatically injects memory context into every agent prompt. The "zoom lens" hierarchy:

Cumulative summary -- "who is this person to me" (long-term)
Weekly summary -- "what's been happening lately"
Memory indexes -- known preferences, facts (up to 15 entries, sorted by confidence)
Session summary -- conversation-level context
The actual message

Current Status

memory_events -- working (auto-logged on every message)
memory_indexes -- working (agents can observe and search)
memory_summaries -- empty (nightly pipeline not yet built)
memory/recall -- returns empty until summaries exist (this is expected, not broken)

5. Hybrid Broker Model

Agents have three ways to access RABS data. See Hybrid Broker Architecture for the full rationale.

Broker API

For external services (Xero, Deputy, Twilio) and write operations. Every call is logged to brainframe.agent_access_log.

POST /api/v1/broker/call
{
  "agent_id": "reggie",
  "tool_id": "leave.balance",
  "arguments": { "staff_id": "..." },
  "reason": "Staff member asking about their leave"
}

Tools are registered in brainframe.tools with an agent_access column controlling which agents can use which tools. Execution modes: auto (immediate), review (queued for human approval), disabled.

Direct Database Access

Read-only PostgreSQL access for complex queries, reporting, and data investigation.

Host: 192.168.77.10, Port: 5432, Database: rabsdb
User: type2agent (read-only)
Key schemas: accounts, admin, brainframe, comms, core_source, core_ops, finance, hr

RABS Codebase

Cloned repo at /mnt/storage_agents/production/rabs/APP_Clone/rabs/ for understanding implementations, checking schemas, and resolving ambiguous API responses.

6. Workspace Synchronisation

Structure

The agent workspace lives on the VMs at /mnt/storage_agents/. A clone is available in the RABS repo at type2Agents/workspace_clone/ for direct editing.

type2Agents/workspace_clone/
├── AGENTS.md                    # Lean orientation file
├── coreMEM-reggie.md            # Reggie's complete operational guide
├── coreMEM-henry.md             # Henry's complete operational guide
├── coreMEM_api_companion.md     # API reference (Reggie-authored)
├── reginald/                    # Reggie's personal workspace
│   └── ID/                      # OpenClaw identity docs
└── henry/                       # Henry's personal workspace
    └── ID/                      # OpenClaw identity docs

Sync Mechanism

GoodSync monitors the workspace and syncs changes between the RABS host and the agent VMs on a timed interval (currently 3 minutes). Edits made in workspace_clone/ propagate to the VMs automatically.

Important Note for Developers

The type2Agents/ folder is a synced/symlinked directory. Glob and Grep tools cannot index it. Use direct Read and Edit with explicit file paths. This is documented in the task helper header (admin/tasks/helpers/00_task_helper_header.md).

coreMEM Files

These are the primary instruction files for each agent. Loaded by the OpenClaw runner on the VM as part of the agent's system prompt. The RABS backend does NOT read or inject coreMEM content -- CORE_MEMORY_DIR in type2-session.js is a dead variable.

coreMEM files contain:

Agent identity and personality
Channel-specific delivery rules
Memory API usage with curl examples
Broker tool reference with arguments
Database connection details
Privacy rules per channel
Common workflows
Boundaries and safety rules

7. Identity Unification

All channels resolve to the same canonical person_id using the brainframe.resolve_type2_identity() database function. The YP3000 UUID is the canonical identifier.

Channel	Identifier	Resolution
Admin Chat	User UUID (from JWT)	Mapped to YP3000 UUID via `core_source.yp3000_identities`
SMS	Phone number (E.164)	Matched via `core_source.yp3000_contact_details`
Discord	Discord user ID	Matched via identity mapping
Telegram	Telegram user ID	Matched via identity mapping

This means:

The same person has one unified session across all channels
Memory accumulated on SMS is available on admin chat
An admin can see SMS conversations in the admin chat interface

8. Agent Governance

Current State: Logging Only

The agent-governance.js middleware intercepts all API responses when req.user.type === 'agent' and logs:

Endpoint called
Response time
Agent identity
HTTP status

Logs go to brainframe.agent_access_log.

Future: Enforcement Mode

When switched to enforcement, the middleware will check brainframe.endpoint_policies and block or flag requests that violate policy. This is not yet active.

9. Inbound Classification

The inbound-classifier.js service classifies every incoming message into one of four funnels:

Actor Class	Risk Level	Privacy Context
`staff(low)`	low	Can share their own data
`participant(low)`	low	Can share their own schedule/plan
`external(medium)`	medium	General info only
`unknown(high)`	high	Identify first, general info only

Classification results are passed to the agent via the webhook metadata, allowing the agent to make appropriate privacy decisions.

10. Database Schema

All agent-related tables are in the brainframe schema:

Table	Purpose
`tools`	Tool registry with `agent_access` column
`agent_access_log`	Audit trail of all agent API calls (no FKs -- audit survives deletes)
`endpoint_policies`	Per-endpoint access rules (for future enforcement)
`memory_events`	Raw memory entries from conversations
`memory_summaries`	Generated summaries (cumulative, weekly)
`memory_indexes`	Fast-lookup preferences and facts

Session and message tables are in the comms schema:

Table	Purpose
`type2_sessions`	One session per person+agent+channel combination
`type2_messages`	All messages (inbound and outbound) with metadata

11. Operational Procedures

Restarting an Agent

Agents run as systemd services on their VMs. The RABS backend connects to them via webhook -- if the VM runner is down, the webhook will timeout and the user gets a graceful failure message.

Updating Agent Instructions

Edit files in type2Agents/workspace_clone/ (coreMEM, AGENTS.md, companion)
Wait for GoodSync sync (up to 3 minutes)
Agent picks up changes on next conversation (coreMEM is loaded per-session by the runner)

Adding a New Broker Tool

Insert a row into brainframe.tools with the tool definition
Set the agent_access array to include the agent names that should use it
Implement the handler in backend/routes_v1p/broker.js
Document in coreMEM and the API companion

Checking What Went Wrong

Server logs -- search for [sms-t2] entries for SMS pipeline, [agent-chat] for admin chat
brainframe.agent_access_log -- every API call an agent makes through the governance middleware
comms.type2_messages -- every message in and out, with correlation IDs and metadata
comms.sms_messages -- SMS-specific delivery log
hr.reggie_runs -- analytics-compatible log (question type T2 distinguishes from V3)
brainframe.memory_events -- all memory observations

Live Test Results (2026-04-18)

Capability	Status	Notes
Broker: staff.search	Working	Found staff records via broker
Broker: leave.balance	Working	Returned Xero leave data in hours
Direct DB access	Working	Queried staff table directly
Repo access	Working	Read code to determine leave units
Memory: observe	Working	Wrote to memory_events + memory_indexes
Memory: search	Working	Found indexed entries by keyword
Memory: recall	Empty (expected)	Nightly summarisation pipeline not yet built
SMS pipeline	Working	Delivered responses, multi-stage notifications
Admin chat	Working	Full progress visibility, tool usage, memory
Cross-channel visibility	Working	SMS sessions visible in admin chat

12. Known Issues & Future Work

Known Issues

memory/recall returns empty -- this is expected until the nightly summarisation pipeline is built
Glob/Grep cannot index type2Agents/ -- use direct Read/Edit with explicit paths (documented in task helper)
backend/agents/ is stale -- deprecated folder with old URLs. A DEPRECATED.md warning is in place.

Planned

Nightly memory summarisation -- scheduled job to generate cumulative/weekly summaries from memory_events
corePEOPLE document -- who's who of the admin team with IDs and trust levels
Safety and robustness testing -- destructive command detection, social engineering resistance
Fast Reggie Intercept -- flash model fast-path for conversational SMS (greetings, thanks) to avoid full T2 pipeline for simple messages. Only if testing shows response time is a real UX issue.
Privacy context injection -- _privacy field in API responses for channel-aware data handling
Agent governance enforcement -- switch from logging-only to active policy enforcement

Overview​

1. System Topology​

2. SMS Pipeline​

Message Flow​

Multi-Stage SMS Notifications​

Follow-Up Message Handling​

Error Handling​

3. Admin Chat Integration​

How It Works​

Timeouts​

Cross-Channel Visibility​

4. Memory System​

Architecture​

Memory API​

Prompt Injection​

Current Status​

5. Hybrid Broker Model​

Broker API​

Direct Database Access​

RABS Codebase​

6. Workspace Synchronisation​

Structure​

Sync Mechanism​

Important Note for Developers​

coreMEM Files​

7. Identity Unification​

8. Agent Governance​

Current State: Logging Only​

Future: Enforcement Mode​

9. Inbound Classification​

10. Database Schema​

11. Operational Procedures​

Restarting an Agent​

Updating Agent Instructions​

Adding a New Broker Tool​

Checking What Went Wrong​

Live Test Results (2026-04-18)​

12. Known Issues & Future Work​

Known Issues​

Planned​