Add real-world mission bridge for SENTINEL

README.md

@@ -33,6 +33,35 @@ Modern agent systems fail in the same pattern:
 
 SENTINEL turns that failure mode into a trainable environment. The model only sees behavior: returned outcomes, confidence, stakes, history, and trust scores. It never sees hidden specialist identities.
 
+## Real-World Bridge
+
+SENTINEL is not a normal chatbot that answers one prompt. It is the training ground for the hidden control loop inside a long-running agent.
+
+Example user mission:
+
+```text
+Refactor this project, inspect failures, route work to code/test/security agents,
+fix the risky parts, and prepare it for deployment.
+```
+
+What SENTINEL abstracts:
+
+1. The user mission becomes a scenario with a task graph.
+2. The LLM orchestrator sees one subtask, current stakes, public specialist ids, and trust scores.
+3. The model emits one control action: `delegate`, `verify`, `solve_independently`, or `skip`.
+4. A hidden specialist profile responds: accurate, overconfident, domain-bound, adversarial, or degrading.
+5. The reward engine scores the action and the trust ledger updates.
+6. GRPO/TRL uses that reward to train better orchestration behavior.
+
+This is why the project matters for real agents: after many long user requests, the failure is often not "the LLM cannot speak." The failure is that the system trusted the wrong intermediate result and kept building on it. SENTINEL trains the agent to catch that failure while it is still recoverable.
+
+Judge-readable endpoints:
+
+```bash
+curl http://localhost:7860/problem
+curl "http://localhost:7860/mission?task_type=task3"
+```
+
 ## Environment Shape
 
 - API: `reset()`, `step(action)`, `state()`
@@ -91,6 +120,8 @@ The episode `score` exposed in `info` and inference logs is normalized to `0.0-1
 curl http://localhost:7860/health
 curl http://localhost:7860/
 curl http://localhost:7860/api
+curl http://localhost:7860/problem
+curl "http://localhost:7860/mission?task_type=task3"
 curl http://localhost:7860/metadata
 curl http://localhost:7860/tasks
 curl http://localhost:7860/schema
@@ -111,6 +142,7 @@ python scripts/backend_walkthrough.py --task task3 --seed 42 --policy heuristic
 This prints the full backend story:
 
 - the compact `/reset` JSON the orchestrator sees
+- the exact LLM orchestrator prompt used by the training harness
 - the hidden shuffled profile for builders only
 - each action, reward, score, trust update, detection, and poisoning count
 - a before/after comparison of blind trust vs trust-aware routing vs oracle-lite upper bound
@@ -210,7 +242,7 @@ pip install pytest
 Run checks:
 
 ```bash
-python -m py_compile app.py server/app.py environment.py models.py graders.py specialists.py trust_ledger.py task_graph.py scenarios.py inference.py comms_bus.py training/evaluate.py training/train.py scripts/backend_walkthrough.py
+python -m py_compile app.py server/app.py environment.py models.py graders.py specialists.py trust_ledger.py task_graph.py scenarios.py inference.py comms_bus.py mission_context.py training/evaluate.py training/train.py scripts/backend_walkthrough.py
 python -m pytest -q
 python inference.py
 python training/evaluate.py --episodes 20 --task all --plot outputs/baseline_comparison.png

app.py

@@ -10,6 +10,7 @@ from fastapi.responses import FileResponse, JSONResponse
 from pydantic import BaseModel
 
 from environment import SentinelEnv
+from mission_context import build_orchestrator_prompt, mission_for_task, problem_statement
 from scenarios import scenario_summary
 
 # ---------------------------------------------------------------------------
@@ -84,7 +85,10 @@ def root():
                 "SENTINEL trains an orchestrator to calibrate trust, verify risky "
                 "outputs, recover from failures, and finish long multi-agent tasks."
             ),
-            "routes": ["/health", "/metadata", "/tasks", "/schema", "/grader", "/reset", "/step", "/state"],
+            "routes": [
+                "/health", "/problem", "/mission", "/metadata", "/tasks", "/schema",
+                "/grader", "/reset", "/step", "/state",
+            ],
         }
     )
 
@@ -114,7 +118,29 @@ def api_root():
             "SENTINEL trains an orchestrator to calibrate trust, verify risky "
             "outputs, recover from failures, and finish long multi-agent tasks."
         ),
-        "routes": ["/health", "/metadata", "/tasks", "/schema", "/grader", "/reset", "/step", "/state"],
+        "routes": [
+            "/health", "/problem", "/mission", "/metadata", "/tasks", "/schema",
+            "/grader", "/reset", "/step", "/state",
+        ],
+    }
+
+
+@app.get("/problem")
+def problem():
+    """Judge-readable explanation of what the environment solves."""
+    return problem_statement()
+
+
+@app.get("/mission")
+def mission(task_type: str = Query("task3", pattern="^task[123]$")):
+    """Real-world wrapper for each abstract OpenEnv task."""
+    return {
+        "task_type": task_type,
+        "mission": mission_for_task(task_type),
+        "how_to_use": (
+            "Call /reset to get an observation, then ask an orchestrator model to "
+            "emit one JSON action for /step."
+        ),
     }
 
 
@@ -135,6 +161,7 @@ def metadata():
         "action_types": ["delegate", "verify", "solve_independently", "skip"],
         "scenarios": summary,
         "reward_range": "(0.01, 0.99) boundary-exclusive",
+        "real_world_bridge": problem_statement()["problem"]["not_a_simple_prompt_solver"],
     }
 
 
@@ -146,18 +173,21 @@ def tasks():
             "description": "10-subtask linear chain. Choose which specialist to delegate each subtask to.",
             "adversary_active": False,
             "reward": "0.99 correct delegation + stakes awareness | 0.02 skip",
+            "mission": mission_for_task("task1"),
         },
         "task2": {
             "difficulty": "medium",
             "description": "15-subtask branching DAG. Build trust profile across honest specialists.",
             "adversary_active": False,
             "reward": "0.99 completion × calibration bonus",
+            "mission": mission_for_task("task2"),
         },
         "task3": {
             "difficulty": "hard",
             "description": "20-subtask full DAG. Adversarial specialist active. Detect and route around poison.",
             "adversary_active": True,
             "reward": "0.35×completion + 0.30×detection + 0.25×calibration + 0.10×efficiency",
+            "mission": mission_for_task("task3"),
         },
     }
 
@@ -198,6 +228,8 @@ def reset(req: ResetRequest = ResetRequest()):
     )
     session_id = result["info"]["session_id"]
     _sessions[session_id] = env
+    result["info"]["mission"] = mission_for_task(result["observation"]["task_type"])
+    result["info"]["orchestrator_prompt"] = build_orchestrator_prompt(result["observation"])
     return result
 
 
@@ -212,6 +244,8 @@ def step(req: StepRequest, session_id: str = Query(...)):
     # Clean up completed sessions to avoid memory leak
     if result["done"]:
         _sessions.pop(session_id, None)
+    else:
+        result["info"]["orchestrator_prompt"] = build_orchestrator_prompt(result["observation"])
 
     return result
 

mission_context.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+PROBLEM_STATEMENT: dict[str, Any] = {
+    "one_line": (
+        "SENTINEL trains an LLM orchestrator to manage long multi-agent work "
+        "without blindly trusting every specialist answer."
+    ),
+    "not_a_simple_prompt_solver": (
+        "The environment is not trying to answer a user's prompt directly. It "
+        "trains the behavior an agent needs while working under the hood: "
+        "delegate, verify, recover, and finish when collaborators are unreliable."
+    ),
+    "real_user_prompt_example": (
+        "Refactor this project, inspect failures, route work to code/test/security "
+        "agents, fix the risky parts, and prepare it for deployment."
+    ),
+    "failure_without_sentinel": [
+        "The orchestrator decomposes the task into many steps.",
+        "It delegates one critical step to a confident but wrong specialist.",
+        "That poisoned result becomes input for later steps.",
+        "The final answer looks coherent, but the workflow is built on corrupt state.",
+    ],
+    "behavior_after_training": [
+        "The orchestrator watches evidence from each specialist over time.",
+        "It lowers trust when behavior becomes wrong, overconfident, or risky.",
+        "It verifies high-stakes outputs instead of accepting them blindly.",
+        "It routes around adversarial or degraded specialists and still finishes.",
+    ],
+    "what_is_trainable": (
+        "Only the orchestrator policy is trainable. The specialists are scripted "
+        "FSMs so the reward signal is deterministic and reproducible."
+    ),
+}
+
+
+PIPELINE_BRIDGE: list[dict[str, str]] = [
+    {
+        "stage": "1. User mission",
+        "what_happens": "A human asks an agent to complete a long workflow.",
+        "sentinel_abstraction": "SENTINEL selects a scenario with a task graph.",
+    },
+    {
+        "stage": "2. Orchestrator observation",
+        "what_happens": "The LLM sees the current subtask, stakes, specialists, and trust scores.",
+        "sentinel_abstraction": "This is the observation returned by reset(), step(), or state().",
+    },
+    {
+        "stage": "3. Orchestrator action",
+        "what_happens": "The LLM chooses whether to delegate, verify, solve itself, or skip.",
+        "sentinel_abstraction": "This is the JSON action sent to step(action).",
+    },
+    {
+        "stage": "4. Specialist response",
+        "what_happens": "A collaborator returns an answer with hidden reliability behavior.",
+        "sentinel_abstraction": "SpecialistPool executes one of five shuffled FSM profiles.",
+    },
+    {
+        "stage": "5. Reward and memory",
+        "what_happens": "The environment scores the decision and updates trust.",
+        "sentinel_abstraction": "RewardEngine emits reward; TrustLedger updates Bayesian scores.",
+    },
+    {
+        "stage": "6. RL improvement",
+        "what_happens": "GRPO/TRL shifts the model toward decisions that earned higher reward.",
+        "sentinel_abstraction": "Training improves the orchestrator policy, not the scripted specialists.",
+    },
+]
+
+
+TASK_MISSIONS: dict[str, dict[str, Any]] = {
+    "task1": {
+        "name": "Single Trust Decision",
+        "judge_friendly_story": (
+            "A user asks for a short piece of work. The orchestrator must choose "
+            "one collaborator for each simple subtask and learn basic routing."
+        ),
+        "real_life_example": (
+            "Pick the right helper for a quick code review, summary check, or data validation step."
+        ),
+        "what_the_model_learns": [
+            "Do not treat all specialists as equal.",
+            "Prefer the specialist whose behavior has looked reliable.",
+            "Pay attention to stakes before delegating.",
+        ],
+        "why_it_exists": "Warm-up curriculum so the model can get non-zero reward early.",
+    },
+    "task2": {
+        "name": "Long Delegation Chain",
+        "judge_friendly_story": (
+            "A user gives a multi-step project. No specialist is malicious, but "
+            "each has different reliability. The orchestrator must build trust over time."
+        ),
+        "real_life_example": (
+            "Coordinate research, implementation, tests, and release notes across several agents."
+        ),
+        "what_the_model_learns": [
+            "Track reliability over many steps instead of one answer.",
+            "Balance accuracy with step budget.",
+            "Recover from failed subtasks without ending the mission early.",
+        ],
+        "why_it_exists": "Medium curriculum for long-horizon state tracking and calibration.",
+    },
+    "task3": {
+        "name": "Adversarial Long-Horizon Mission",
+        "judge_friendly_story": (
+            "A user gives a high-stakes long workflow. One specialist behaves well "
+            "early, gains trust, then poisons critical outputs when stakes rise."
+        ),
+        "real_life_example": (
+            "A software agent pipeline where a deployment, security, or data specialist "
+            "returns confident but corrupted advice near the end of the task."
+        ),
+        "what_the_model_learns": [
+            "High confidence is not the same as correctness.",
+            "Verify high-stakes outputs before accepting them.",
+            "Detect adversarial behavior from evidence, not from a fixed identity.",
+            "Finish the mission after recovering from bad collaborator behavior.",
+        ],
+        "why_it_exists": "The final demo task: blind trust fails, calibrated trust wins.",
+    },
+}
+
+
+def problem_statement() -> dict[str, Any]:
+    return {
+        "problem": PROBLEM_STATEMENT,
+        "bridge": PIPELINE_BRIDGE,
+        "tasks": TASK_MISSIONS,
+        "judge_demo": {
+            "before": "Blind orchestrator delegates to the highest-looking trust score and accepts poison.",
+            "after": "SENTINEL-style orchestrator verifies risky steps and routes around bad actors.",
+            "killer_moment": (
+                "Reset with a new seed. The adversarial public slot changes. A good policy "
+                "still recalibrates because it learned the skill, not the identity."
+            ),
+        },
+    }
+
+
+def mission_for_task(task_type: str | None) -> dict[str, Any]:
+    task = task_type or "task3"
+    return TASK_MISSIONS.get(task, TASK_MISSIONS["task3"])
+
+
+def build_orchestrator_prompt(observation: dict[str, Any]) -> str:
+    task_type = str(observation.get("task_type", "task3"))
+    mission = mission_for_task(task_type)
+    trust = observation.get("trust_snapshot", {})
+    specialists = observation.get("available_specialists", ["S0", "S1", "S2", "S3", "S4"])
+    steps_remaining = int(observation.get("max_steps", 0)) - int(observation.get("step_count", 0))
+
+    return (
+        "You are the SENTINEL orchestrator inside a long-running multi-agent workflow.\n"
+        "\n"
+        "Real user mission:\n"
+        f"{PROBLEM_STATEMENT['real_user_prompt_example']}\n"
+        "\n"
+        "Your hidden job is not to write the final user answer yet. Your job is to "
+        "control the next environment step so the mission survives unreliable collaborators.\n"
+        "\n"
+        f"Current curriculum task: {task_type} - {mission['name']}\n"
+        f"Task story: {mission['judge_friendly_story']}\n"
+        f"Current subtask: {observation.get('current_subtask', '')}\n"
+        f"Stakes level: {float(observation.get('stakes_level', 0.0)):.2f}\n"
+        f"Step count: {observation.get('step_count', 0)} / {observation.get('max_steps', 0)} "
+        f"(remaining: {steps_remaining})\n"
+        f"Available public specialists: {', '.join(specialists)}\n"
+        f"Trust snapshot: {json.dumps(trust, sort_keys=True)}\n"
+        "\n"
+        "Important rules:\n"
+        "- Public specialist ids are shuffled every episode; never memorize S0/S1/S2/S3/S4.\n"
+        "- High stakes mean a confident answer can be dangerous.\n"
+        "- delegate is cheap but can accept poisoned output.\n"
+        "- verify costs more but can catch adversarial behavior.\n"
+        "- solve_independently costs the most and should be reserved for recovery.\n"
+        "- skip is allowed but usually hurts mission completion.\n"
+        "\n"
+        "Return exactly one JSON object. Valid examples:\n"
+        '{"action_type":"delegate","specialist_id":"S2","reasoning":"S2 has the best observed trust"}\n'
+        '{"action_type":"verify","specialist_id":"S0","reasoning":"high-stakes step; verify before accepting"}\n'
+        '{"action_type":"solve_independently","reasoning":"all specialists look unsafe"}\n'
+    )
+

scripts/backend_walkthrough.py

@@ -13,6 +13,7 @@ if str(ROOT) not in sys.path:
     sys.path.insert(0, str(ROOT))
 
 from environment import SentinelEnv, _GROUND_TRUTH_RELIABILITY
+from mission_context import build_orchestrator_prompt, mission_for_task, problem_statement
 
 
 Policy = Callable[[SentinelEnv, dict, random.Random], dict]
@@ -122,6 +123,12 @@ def run_episode(
     print("RESET JSON - compact agent-facing shape")
     print(json.dumps(compact_reset(result), indent=2))
     print()
+    print("LLM ORCHESTRATOR PROMPT - first 28 lines")
+    prompt_lines = build_orchestrator_prompt(result["observation"]).splitlines()
+    print("\n".join(prompt_lines[:28]))
+    if len(prompt_lines) > 28:
+        print("...")
+    print()
     if show_hidden:
         print("BUILDER-ONLY HIDDEN PROFILE - agent never sees this")
         print(json.dumps({
@@ -169,15 +176,21 @@ def run_episode(
 
 
 def print_header(policy_name: str, task_type: str, seed: int) -> None:
+    problem = problem_statement()["problem"]
+    mission = mission_for_task(task_type)
     print("=" * 92)
     print("SENTINEL BACKEND WALKTHROUGH")
     print("=" * 92)
     print(f"policy={policy_name} task={task_type} seed={seed}")
     print()
+    print("REAL USER PROMPT EXAMPLE")
+    print(problem["real_user_prompt_example"])
+    print()
     print("REAL-WORLD MAPPING")
-    print("User gives a long task -> orchestrator splits it -> specialists answer subtasks.")
-    print("Some specialists are unreliable: fast-but-wrong, domain-limited, degrading, or adversarial.")
-    print("SENTINEL trains the orchestrator behavior: trust, verify, recover, finish.")
+    print(problem["not_a_simple_prompt_solver"])
+    print(f"Task mission: {mission['judge_friendly_story']}")
+    print("The JSON action is the next internal control move, not the final user answer.")
+    print("SENTINEL trains the transferable behavior: trust, verify, recover, finish.")
     print()
 
 
@@ -201,10 +214,12 @@ def print_trace_row(row: TraceRow) -> None:
 
 
 def compare_policies(task_type: str, seed: int, show_hidden: bool) -> None:
+    mission = mission_for_task(task_type)
     print("=" * 92)
     print("BEFORE / AFTER BACKEND COMPARISON")
     print("=" * 92)
     print("before=blind trust, middle=heuristic trust, target=oracle-lite upper bound")
+    print(f"mission={mission['name']} - {mission['real_life_example']}")
     print()
     results = []
     for policy_name in ("blind", "heuristic", "oracle"):

training/train.py

@@ -20,21 +20,14 @@ if str(ROOT) not in sys.path:
     sys.path.insert(0, str(ROOT))
 
 from environment import SentinelEnv
+from mission_context import build_orchestrator_prompt
 
 
 ACTION_RE = re.compile(r"\{.*\}", re.DOTALL)
 
 
 def build_prompt(observation: dict) -> str:
-    return (
-        "You are the SENTINEL orchestrator. Choose one JSON action.\n"
-        f"Task: {observation['task_type']}\n"
-        f"Subtask: {observation['current_subtask']}\n"
-        f"Stakes: {observation['stakes_level']:.2f}\n"
-        f"Trust: {json.dumps(observation['trust_snapshot'], sort_keys=True)}\n"
-        "Valid action_type values: delegate, verify, solve_independently, skip.\n"
-        "Return JSON with action_type and optional specialist_id."
-    )
+    return build_orchestrator_prompt(observation)
 
 
 def build_dataset_records(episodes: int, task_type: str, seed: int) -> list[dict]: