Studio Hathor · NPC Behavior Trees

Purpose#

Admin lane console for the real @hathor/llm-npc BehaviorController schedule resolver. Against a daily schedule (weekday / weekend / special-day time blocks), it resolves which activity is active at a given hour — matching time ranges with overnight wraparound (a 22→6 block covers hour 23 and hour 3) and giving special-day blocks precedence over the regular schedule. Admin-scoped and fail-closed.

Entry points#

• Quick-action link from /studio/hathor/scenario-generation (this page links out to scenario-generation)
• Direct URL / bookmark — yes; alternates.canonical set
• Studio overview — see ../../studio-overview.md

Layout regions#

page.tsx renders inside <ShellLayout active="studio">:

• Workspace <section data-hathor-npc-behavior-trees-workspace>:
  • <h1> (WorkspaceHeading) "Hathor NPC Behavior Trees Workspace"
  • Summary <p data-hathor-npc-behavior-trees-summary>
  • Seeded daily schedule (<h2>) — read-only data-hathor-nbt-schedule list of data-hathor-nbt-schedule-item rows (weekday + weekend blocks)
  • The resolve form lane: data-hathor-nbt-resolve-form
• Route Map panel (data-hathor-npc-behavior-trees-route-map): <h2> "Route Map" + 5 entries from STUDIO_HATHOR_NPC_BEHAVIOR_TREES_ROUTE_MAP
• Quick-action lane: two Link.quickAction anchors — Scenario Generation, Back to Studio workspace index

States#

• Loading — <p data-hathor-nbt-loading>
• Unauthorized — data-hathor-nbt-unauthorized on 401/403 (admin Hathor scope required); fail-closed
• Error — data-hathor-nbt-error on non-OK GET / malformed catalog
• Ready (form) — seeded schedule + data-hathor-nbt-resolve-form once the catalog loads
• Result — data-hathor-nbt-result after a 200 resolve; data-hathor-nbt-resolve-error for invalid inputs / non-200

Interactions#

Workspace body (resolve form lane)#

• Hour (0–24) — <input data-hathor-nbt-field-hour> (aria-label "hour")
• weekend — <input data-hathor-nbt-field-weekend type="checkbox"> (aria-label "is weekend")
• Special day (optional) — <input data-hathor-nbt-field-special> (aria-label "special day")
• Resolve activity — <button data-hathor-nbt-resolve-submit type="submit"> → POST /v1/admin/hathor/npc-behavior-trees/resolve
• Result — data-hathor-nbt-activity, data-hathor-nbt-scheduled, and (when a block matches) data-hathor-nbt-matched

Route Map panel#

• 5 route entries — verify match with STUDIO_HATHOR_NPC_BEHAVIOR_TREES_ROUTE_MAP

Quick-action lane#

• "Open Hathor Scenario Generation workspace" (→ /studio/hathor/scenario-generation)
• "Back to Studio workspace index" (→ /studio)

Data & contracts#

• Reads: GET /v1/admin/hathor/npc-behavior-trees on mount
• Writes: POST /v1/admin/hathor/npc-behavior-trees/resolve
• Realtime: none
• Caching: client fetch on mount, cache: 'no-store'; buildBffAuthHeaders
• Auth/role check: admin-scoped fail-closed (401/403); behind the signed-in
  • studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-hathor-llm-npc.md, ./studio-hathor-scenario-generation.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorNpcBehaviorTreesWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorNpcBehaviorTreesRouteMap.ts

Open questions / known gaps#

• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv. Confirm whether the dedicated /studio/hathor/* admin lane consoles ship in V1.
• The lane queries a single seeded schedule rather than letting the operator author or upload a tree; confirm whether schedule editing / behavior-tree authoring is planned for this route despite the name.
• Route Map advertises trees/, templates/, agents/, and governance/ sub-routes with no page.tsx yet.