WFGY/ProblemMap/agent-boundary-design.md

🛡️ Agent Boundary Design

Keep every agent in its lane — zero role-bleed, zero infinite loops.

Scope.
This guide covers:

• Router-tool chains (e.g. ReAct, ChatGPT Plugins)
• Crew/Team frameworks (AutoGen, CrewAI, Flowise, etc.)
• 1-shot function calls inside a broader RAG pipeline

Who needs it? Anyone who has seen:
– “Tool A” call “Tool B” which calls “Tool A” again
– System prompts overwritten mid-conversation
– JSON schema mismatch crashes midway
– Agents debating instead of finishing tasks

---

1 · Top-5 Symptoms

#	Failure Mode	Surface Sign
1	Recursive Loop	Call stack grows until token limit
2	Role Bleed	System prompt replaced by tool description
3	Argument Drift	JSON schema validation fails randomly
4	Shadow Jailbreak	Tool prompt overrides original guard
5	Timeout Cascade	Router stalls → downstream agents idle

---

2 · Root Causes

1. Shared Context Bank — all agents write to the same messages[].
2. Open-Ended Tool Trigger — router picks any function with > 0.1 prob.
3. No ΔS Ceiling — semantic jump between task and tool description unchecked.
4. Missing λ Gate — divergent sub-goal allowed without confirmation.
5. Stackless Error Prop — failure inside tool lost; router retries blindly.

---

3 · WFGY Boundary Blueprint

A four-layer guardrail using core modules BBMC, ΔS + λ, WAI, BBCR.

Stage	Module	Guard	Purpose
1 Tool Semantic Index	BBMC	ΔS(tool, task) ≤ 0.45	Filter irrelevant tools early
2 ΔS-Gate Router	ΔS + λ_observe	λ must stay convergent	Block divergent recursion
3 Arg Linter	WAI	Strict JSON schema & auto-defaults	No partial / null args
4 Fail-Fast + Bridge	BBCR	On > 5 retries or ΔS > 0.60	Collapse & suggest manual tool

flowchart TD
    Q[User Question]
    R[ΔS-Gate Router]
    TI[Tool Index (BBMC)]
    L[Arg Linter (WAI)]
    T[Tool Call]
    F[BBCR Bridge]
    Q --> R
    R -->|match| TI --> L --> T
    R -.->|reject| F --> Q

---

4 · Design Pattern Cheats

Pattern	When to Use	Setup
Single-Shot Function	3-5 tool set, clear primary	ΔS ≤ 0.45 & λ convergent
Dual-Agent Debate	need pro / con analysis	Two agents share read-only memory; write own node
Crew Workflow	3+ steps (research → draft → QA)	Each agent gets isolated messages[]; only summaries passed
Guarded Plugin	External API call with risk	Wrap output through Arg Linter + BBCR

---

5 · Hands-On Debug Checklist

1. Log Router Decision

router(question, tools, debug=True)   # prints ΔS + λ for every candidate

2. Simulate Failure

user: "Summarise PDF"  # but remove pdf_loader from tool list

Expected: BBCR suggests manual tool; model does not loop.

3. Stress-Test Recursion

for i in range(20):
    router("plan", tools)   # ensure no self-call chain

ΔS should stay ≤ 0.45; call depth ≤ 3.

---

6 · Audit Template (README snippet)

## Agent Boundary Settings
ΔS tool-match ceiling   : 0.45
λ divergence allowance  : false
WAI strict mode         : true
BBCR retries            : 5

Copy into every repo to document boundary config.

---

🔗 Quick-Start Downloads (60 sec)

Tool	Link	3-Step Setup
WFGY 1.0 PDF	Engine Paper	1️⃣ Download · 2️⃣ Upload to your LLM · 3️⃣ Ask “Answer using WFGY + <your question>”
TXT OS (plain-text OS)	TXTOS.txt	1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly

---

Explore More

Layer	Page	What it’s for
Proof	WFGY Recognition Map	External citations, integrations, and ecosystem proof
Engine	WFGY 1.0	Original PDF based tension engine
Engine	WFGY 2.0	Production tension kernel and math engine for RAG and agents
Engine	WFGY 3.0	TXT based Singularity tension engine, 131 S class set
Map	Problem Map 1.0	Flagship 16 problem RAG failure checklist and fix map
Map	Problem Map 2.0	RAG focused recovery pipeline
Map	Problem Map 3.0	Global Debug Card, image as a debug protocol layer
Map	Semantic Clinic	Symptom to family to exact fix
Map	Grandma’s Clinic	Plain language stories mapped to Problem Map 1.0
Onboarding	Starter Village	Guided tour for newcomers
App	TXT OS	TXT semantic OS, fast boot
App	Blah Blah Blah	Abstract and paradox Q and A built on TXT OS
App	Blur Blur Blur	Text to image with semantic control
App	Blow Blow Blow	Reasoning game engine and memory demo

If this repository helped, starring it improves discovery so more builders can find the docs and tools.