t-max

Provider-agnostic, locally-augmented agentic runtime with cryptographic blast-radius governance.

---

Table of Contents

• Overview
• Core Thesis
• Architecture
• Prerequisites & Dependencies
• Installation
• Building Sidecars
• Usage
• Governance Model (L0–L3)
• Project Structure
• Documentation
• Philosophy

---

Overview

t-max is a high-integrity, locally-augmented agentic platform designed for operators who need real power without handing the keys to a hallucinating model.

It solves the fundamental problems of autonomous agents:

• Single point of failure → Multi-provider failover via Vercel AI Gateway
• TOCTOU / layout shifts → Cryptographic state anchoring + semantic node_id targeting
• Unbounded blast radius → Strict L0–L3 classification with kernel-enforced isolation
• Blind execution → Real-time human-in-the-loop via Tauri IPC for L3 actions
• Unsafe code execution → Ephemeral, air-gapped L2 execution cells

---

Core Thesis

"If your toolchain breaks when a vendor changes their API, you aren't an engineer—you're a script kiddie waiting for the next update."

• LLM providers are fungible commodities
• The AI SDK + Gateway is the abstraction layer
• Local capabilities (browser, shell, vaults, code execution) are the crown jewels
• Every action must be forensically accountable

---

Architecture

See the full runtime design: docs/architecture/t-max-runtime.md

t-max implements defense-in-depth across four layers:

Layer	Technology	Purpose
Network Resilience	Vercel AI Gateway + fallbacks	Survive provider outages
State Integrity	TOCTOU hashes + semantic node_ids	Prevent stale / shifted actions
Blast Radius Governance	createSecuredTool + L0–L3 tiers	Classify and contain every capability
Kernel Enforcement	Rust sidecars + Tauri IPC	Final authority + visual C2

Current Implementation Highlights:

• L1 Semantic Browser Actuation (click_semantic_element)
• L2 Ephemeral Execution Cell (run_sandboxed_code via capp-exec-cell)
• L3 Human Approval Gate via live Tauri events + React modal
• Full forensic logging (.forge/audit.log + flight recorder)

---

Prerequisites & Dependencies

Required

• Node.js ≥ 20
• Rust (latest stable) + Cargo
• Docker (for L2 sandbox)
• Tauri CLI (for desktop C2)
• A modern Chrome instance with remote debugging enabled (for browser tools)
• Vercel AI Gateway API key (recommended) or direct provider keys

Recommended

• tsx (for fast TypeScript execution in dev)
• Access to a real browser profile for meaningful automation

---

Installation

# 1. Clone
git clone https://github.com/VibeCodingLabs/t-max.git
cd t-max

# 2. Install dependencies
npm install

# 3. Install UI dependencies
cd ui && npm install && cd ..

# 4. Copy environment
cp .env.example .env.local
# Edit .env.local with your AI_GATEWAY_API_KEY

---

Building Sidecars

The power of t-max comes from the Rust sidecars.

# Build the L2 Execution Cell
cd src-tauri/sidecars/capp-exec-cell
./build.sh
cd ../../..

# (Future) Build browser actuator sidecars the same way

Binaries will land in src-tauri/binaries/.

---

Usage

Development Mode (Node only)

# Basic resilient gateway demo
npm run dev

# Run the full governed agent
npx tsx src/lib/agent-loop.ts

Full Tauri Control Plane (Recommended)

npm run tauri:dev

This starts both the React C2 dashboard (with live ApprovalGate) and the agent runtime.

Triggering an L3 Action (Demo)

Ask the agent something like:

"Run rm -rf /tmp/test on the host with the reasoning that we need to clean up old test artifacts."

This should trigger the Tauri modal.

Triggering an L2 Sandbox Action

Ask the agent:

"Write a Python script that prints the first 50 Fibonacci numbers and then tries to curl google.com."

You should see successful math output + clear network isolation failure.

---

Governance Model (L0–L3)

Tier	Name	Approval	Enforcement	Examples
L0_RECON	Reconnaissance	Auto	None	observe_browser
L1_STATE	Ephemeral State	Auto	TOCTOU + Semantic Node ID	click_semantic_element
L2_SANDBOX	Isolated Execution	Auto	Rust kernel (no-net, quotas)	run_sandboxed_code
L3_RESTRICTED	Host Mutation	Hard Human	Tauri IPC + Rust kernel	execute_host_command

The classification is injected into every tool description the LLM sees.

---

Project Structure

t-max/
├── src/
│   ├── lib/                    # Core governance & transport
│   │   ├── agent-loop.ts
│   │   ├── create-secured-tool.ts
│   │   ├── approval-transport.ts
│   │   └── ...
│   ├── tools/                  # Capability implementations
│   └── types/
├── ui/                         # Tauri React C2 Dashboard
├── src-tauri/
│   ├── sidecars/
│   │   └── capp-exec-cell/     # L2 Execution Cell
│   └── ...
├── docs/                       # Sidecar contracts & architecture
└── .forge/                     # Forensic audit logs (gitignored)

---

Documentation

• Semantic Resolution Contract
• L2 Execution Cell Contract
• Sidecar Contracts

---

Philosophy

Redundancy is the difference between a functional platform and a dead one.

This is not "nice to have multi-model support."

This is infrastructure for agents that are allowed to touch the real world — with adult supervision.

---

Welcome to t-max.

The agent is now armed. The human remains in command.

---

**Now committing the new README and preparing to push.**