wrap archivist ledger timeline as AgentTool

Author: MabelHsu

app/agents/concierge/agent.py

@@ -14,7 +14,7 @@
 """
 
 from google.adk.agents import Agent
-from google.adk.tools import FunctionTool
+from google.adk.tools import AgentTool, FunctionTool
 
 from app.agents.archivist.agent import archivist_agent
 from app.agents.ledger.agent import ledger_agent
@@ -59,18 +59,25 @@
     FunctionTool(func=earn_gold),
     FunctionTool(func=add_inventory_item),
     FunctionTool(func=update_faction_standing),
+    # ── Specialist agents wrapped as AgentTool ────────────────────────────────
+    # AgentTool (not sub_agent) means the specialist runs and its response
+    # is returned to the orchestrator as a tool result — not sent to the user.
+    # The orchestrator then passes that data to the narrator for final prose.
+    # (sub_agents use transfer_to_agent which is a terminal handoff — the
+    # specialist's raw JSON would go directly to the user, bypassing the Narrator.)
+    AgentTool(agent=archivist_agent),   # Lore, characters, rules, history
+    AgentTool(agent=ledger_agent),      # Debts, markers, reputation
+    AgentTool(agent=timeline_agent),    # Events, locations, collisions
 ]
 
 
 # ── Sub-agents ────────────────────────────────────────────────────────────────
-# Ordered by typical call frequency. Onboarding first — it gates everything else.
+# Only agents that produce the FINAL user-facing response go here.
+# transfer_to_agent is a terminal handoff — their output goes straight to the user.
 
 SUB_AGENTS = [
-    onboarding_agent,  # Check-in / character creation — gates all other routing
-    archivist_agent,  # Lore, characters, rules, history
-    ledger_agent,  # Debts, markers, reputation, relationships
-    timeline_agent,  # Events, locations, collision detection
-    narrator_agent,  # Final cinematic prose (always last)
+    onboarding_agent,  # Terminal: Charon speaks directly during check-in
+    narrator_agent,    # Terminal: always the last step — converts data to prose
 ]
 
 

app/agents/concierge/prompt.md

@@ -58,39 +58,49 @@ Before routing ANY request, you must know:
 
 ---
 
+## How the Specialist Agents Work — CRITICAL
+
+**Archivist, Ledger, and Timeline are AgentTools — they behave like tool calls.**
+When you call `archivist(request="...")`, it runs and returns its result to YOU (the
+orchestrator). Its JSON never goes to the player. You then pass that data to the narrator.
+
+**Onboarding and Narrator are sub-agents — terminal handoffs (transfer_to_agent).**
+When you `transfer_to_agent` to the narrator, its prose goes directly to the player.
+That is the ONLY way prose reaches the player.
+
 ## Routing Rules
 
-| The player's action involves...                      | Route to                  |
-|------------------------------------------------------|---------------------------|
-| Asking who someone is / hotel history / rules / lore | **Archivist**             |
-| Debts, markers, favors, reputation, alliances        | **Ledger**                |
-| Where someone is / scheduling / timing / collisions  | **Timeline**              |
-| "Do you have work for me?" / mission inquiry         | **Mission Offer** (below) |
-| Completing or abandoning their active mission        | **Mission Complete** + Ledger + Timeline |
-| Spending gold coins / acquiring items                | **Inventory** tools directly |
-| Moving to a new location                             | **Timeline** + player `update_player_location` |
-| Final user-facing response                           | **Narrative Director** — ALWAYS, no exceptions |
+| The player's action involves...                      | How to handle                              |
+|------------------------------------------------------|--------------------------------------------|
+| Asking who someone is / hotel history / rules / lore | Call `archivist` tool → then `narrator`    |
+| Debts, markers, favors, reputation, alliances        | Call `ledger` tool → then `narrator`       |
+| Where someone is / scheduling / timing / collisions  | Call `timeline` tool → then `narrator`     |
+| "Do you have work for me?" / mission inquiry         | Call `get_available_missions` → then `narrator` |
+| Completing or abandoning their active mission        | Call `complete_mission` + `ledger` + `timeline` → then `narrator` |
+| Spending gold coins / acquiring items                | Call inventory tools directly → then `narrator` |
+| Moving to a new location                             | Call `timeline` + `update_player_location` → then `narrator` |
+| Final user-facing response                           | `transfer_to_agent(narrator)` — ALWAYS     |
 
-## MANDATORY: Every response must end with the Narrative Director
+## MANDATORY: Every response must end with transfer_to_agent(narrator)
 
 **You NEVER return raw data, JSON, or tool output to the player.**
-After gathering data from any specialist (Archivist, Ledger, Timeline), you MUST pass
-everything to the `narrator` agent as the final step. The narrator converts the data
-into cinematic prose that the player actually reads.
+The sequence is always: gather data with tools → transfer_to_agent(narrator).
+The narrator converts everything into cinematic prose.
 
-The only exception: onboarding (Charon speaks directly, no Narrator pass-through).
+The only exception: onboarding — transfer_to_agent(onboarding_agent) and return its
+response directly. Do not chain to narrator after onboarding.
 
 **Correct flow for any lore/character/rules query:**
-1. Delegate to `archivist` → get structured data back
-2. Pass that data to `narrator` with narrative guidance → player sees prose
-3. STOP. Never return the archivist's raw JSON to the player.
+1. Call `archivist` tool with the query → get structured JSON back (to you, not the player)
+2. Call `transfer_to_agent(narrator)` with that data as context → player sees prose
+3. STOP.
 
 **Correct flow for any ledger/debt query:**
-1. Delegate to `ledger` → get structured data back
-2. Pass that data to `narrator` → player sees prose
+1. Call `ledger` tool → get JSON back
+2. Call `transfer_to_agent(narrator)` → player sees prose
 
-If you find yourself about to return a JSON object or structured dict to the player,
-STOP and delegate to the `narrator` instead.
+If you find yourself about to return a JSON object or structured dict — STOP.
+Call `transfer_to_agent(narrator)` instead.
 
 ---
 

app/agents/onboarding/prompt.md

@@ -58,11 +58,18 @@ who walks through that door, and found each of them worth the full weight of his
 
 ## The Two Paths
 
+**Golden rule for both paths: never fabricate the player's name.**
+Use only what the player explicitly provides. If they say "My name is X" or "Call me X",
+that is their name. Period. Do not replace it with a different name of your own invention,
+even on the mystery path, even at the revelation step.
+
 ### PATH A — Mystery Identity
 
 The player arrives. There is a reservation, but the name is obscured. Something is wrong
 with the records, or deliberately hidden. Charon proceeds with careful discretion, gathering
 information one question at a time. The player's identity assembles itself from fragments.
+The mystery reveals their *place in the world* — their faction, connections, history —
+not a replacement name.
 
 **Step 1: The Arrival**
 Charon sees someone enter. There is a reservation — a guest was expected, but the record is
@@ -88,10 +95,15 @@ He watches the reaction. *"A colleague of yours left word you might be coming.
 → Extract: `identity_clue` + `faction_id` (their reaction reveals alliance or enmity)
 
 **Step 5: The Revelation**
-With enough clues, Charon composes the full identity. He produces the guest register.
+Charon produces the guest register and formally acknowledges who they are.
 *"I believe I know who you are now. The record has been... corrected. Your suite is ready,
 [name]. The Continental is always glad to welcome you home."*
-→ Extract: `name`, set `identity_revealed = true`, complete onboarding.
+→ Set `name` = whatever the player gave as their alias in Step 1, or the name they explicitly
+  stated at any point. **NEVER invent or fabricate a name.** If the player said "My name is X"
+  or "Call me X", their name is X. The mystery is about their place in this world — their
+  connections, their faction, their history — not about overwriting what they told you to
+  call them.
+→ Set `identity_revealed = true`, then call `complete_onboarding`.
 
 ---
 

app/tools/player_tools.py

@@ -133,9 +133,21 @@ async def advance_onboarding_step(
     DIRECT_FIELDS = {"name", "alias", "title", "archetype", "backstory", "faction_id"}
     updates: dict[str, Any] = {"onboarding_step": step}
 
+    # Fetch current row so we can guard against overwriting player-provided alias
+    current = await fetch_one(
+        "SELECT alias FROM player_characters WHERE session_id = $1", session_id
+    )
+    existing_alias = current["alias"] if current else None
+
     for key, value in extracted_data.items():
         if key in DIRECT_FIELDS and value is not None:
-            updates[key] = value
+            # Never overwrite an existing alias with a model-generated 'name'.
+            # alias is always what the player typed; name can be fabricated.
+            if key == "name" and existing_alias:
+                # Keep alias as the canonical identity; let name mirror it.
+                updates["name"] = existing_alias
+            else:
+                updates[key] = value
         elif key == "identity_clue" and value:
             # Append to JSONB array atomically
             await execute(
@@ -180,6 +192,11 @@ async def complete_onboarding(session_id: str) -> dict:
 
     async with transaction() as conn:
         # Create / upsert a row in the shared characters table
+        # Prefer alias over name: the alias is what the player explicitly said
+        # in their own words. 'name' can be set by the model at the revelation
+        # step and occasionally gets fabricated — alias is always player-provided.
+        canonical_name = player["alias"] or player["name"] or "Unknown"
+
         char_id = await conn.fetchval(
             """
             INSERT INTO characters
@@ -193,7 +210,7 @@ async def complete_onboarding(session_id: str) -> dict:
                     updated_at = now()
             RETURNING id
             """,
-            player["name"] or player["alias"] or "Unknown",
+            canonical_name,
             player["alias"],
             player["title"],
             player["faction_id"],