v3.3.0 — Phase 4: Behavioral Control Plane

[Jovancoding]

What's New in v3.3.0

Phase 4 adds a full Behavioral Control Plane — a layer that governs which agents can act, with which tools, in which workflow states, with real-time violation monitoring and MCP-compatible blackboard tool bindings.

---

🔒 FSM Journey Layer (lib/fsm-journey.ts)

• JourneyFSM — Finite-state machine that gates agent actions and tool calls by workflow state. Agents outside their authorized state are blocked before execution.
• ToolAuthorizationMatrix — Per-agent, per-state tool allowlist with '*' wildcard support. Grant or revoke at runtime without restarting.
• ComplianceMiddleware — Wraps async/sync agent actions; throws ComplianceViolationError if the FSM denies the agent or tool.
• WORKFLOW_STATES — Built-in constants: INTAKE → VALIDATE → RESEARCH → PLAN → EXECUTE → REVIEW → DELIVER → COMPLETE → ERROR
• createDeliveryPipelineFSM() — One-call factory that wires a complete 9-state delivery pipeline with role-based transitions and tool permissions pre-configured.

const fsm = createDeliveryPipelineFSM({
  orchestratorId: 'orchestrator',
  researchAgentId: 'data_analyst',
  executorId: 'code_writer',
  reviewerId: 'reviewer',
});

const guard = new ComplianceMiddleware(fsm);
fsm.transition('validate', 'orchestrator');
fsm.transition('start_research', 'orchestrator');

// Throws ComplianceViolationError if agent/tool not authorized in current state
await guard.enforce('data_analyst', 'query_db', async () => db.query('...'));

---

📡 Real-Time Compliance Monitor (lib/compliance-monitor.ts)

• ComplianceMonitor — Async polling loop that continuously checks for:
  • RESPONSE_TIMEOUT — Agent silent longer than configured limit
  • JOURNEY_TIMEOUT — FSM state exceeded its timeoutMs
  • TURN_TAKING — Single agent took 5+ consecutive actions without yielding
  • TOOL_ABUSE — Tool called more than maxToolCallsPerWindow in the rate window
• Configurable per-agent via setAgentConfig(), violations queryable via getViolations() and getSummary()

const monitor = new ComplianceMonitor({
  pollIntervalMs: 5_000,
  fsm,
  agentConfigs: [{ agentId: 'data_analyst', responseTimeoutMs: 30_000, maxToolCallsPerWindow: 10 }],
  onViolation: (v) => alerting.send(v),
});
monitor.start();
monitor.recordAction({ agentId: 'data_analyst', action: 'query', tool: 'query_db' });

---

🔧 MCP Blackboard Tool Bindings (mcp-blackboard-tools.ts)

• BlackboardMCPTools — Wraps any SharedBlackboard instance and exposes it as 5 MCP-compatible tool definitions so any LLM agent can interact with shared state via standard tool calls:
  • blackboard_read — Read a single entry by key
  • blackboard_write — Write a value (with optional TTL and agent token)
  • blackboard_list — List all keys with optional prefix filter
  • blackboard_delete — Delete an entry by key
  • blackboard_exists — Check if a key exists and hasn't expired
• registerBlackboardTools(mcpAdapter, blackboard) — Register all 5 tools on any MCP adapter in one call
• BLACKBOARD_TOOL_DEFINITIONS — Exported JSON schema array for all 5 tools

const tools = new BlackboardMCPTools(orchestrator.getBlackboard());
const result = await tools.call('blackboard_write', {
  key: 'research:findings',
  value: JSON.stringify({ insights: [...] }),
  agent_id: 'data_analyst',
});

---

📦 New Exports

All Phase 4 classes and types are available from network-ai:

import {
  JourneyFSM, ToolAuthorizationMatrix, ComplianceMiddleware,
  ComplianceViolationError, createDeliveryPipelineFSM, WORKFLOW_STATES,
  ComplianceMonitor,
  BlackboardMCPTools, registerBlackboardTools, BLACKBOARD_TOOL_DEFINITIONS,
} from 'network-ai';

---

🧪 Tests

462 total — all passing (up from 315)

Suite	Tests	Coverage
test-standalone.ts	79	Blackboard, auth, integration, parallelization, quality gate
test-security.ts	33	Tokens, sanitization, rate limiting, encryption, audit
test-adapters.ts	139	All 12 adapters + registry routing
test-priority.ts	64	Priority preemption, conflict resolution
test-phase4.ts	147	FSM transitions, tool matrix, compliance middleware, monitor, MCP tools

---

📋 New npm Script

npm run test:phase4   # 147 Phase 4 tests
npm run test:all      # all 462 tests

---

Full Changelog: v3.2.11...v3.3.0

---

This discussion was created from the release v3.3.0 — Phase 4: Behavioral Control Plane.