Mode Tool/Node Capability Contract

Contract Topology

flowchart LR
  A["Agent manifest"] --> B["Resolve tool ids"]
  B --> C["Tool policy"]
  C --> D["Node registry"]
  D --> E["Workspace renderer"]
  E --> F["Action proposals"]
  F --> G["Human decision"]
  G --> H["Persisted nodes"]

จุดสำคัญคือ contract นี้ทำให้ “สิ่งที่ agent ขอได้” ตรงกับ “สิ่งที่ workspace เก็บและแสดงได้”

Capability Matrix

Mode	Node types หลัก	Tool behavior
`general`	(ไม่มี workspace nodes โดยตรง)	chat-centric tools
`idea`	`idea`, `research_result`, `concept`, `master_vision`, `frame`, `action_plan`, `action_task`, `document`	proposal-heavy + HITL
`strategy`	`strategy_item`	framework-based proposal + HITL
`maps`	`location`, `heat_zone`, `air_quality`, `route_path`, `point_cluster`, `area_zone`	geospatial actions + realtime apply
`analytics`	dashboard/widget context objects	dataset/template-driven actions

Decision Flow (Tool -> Node)

sequenceDiagram
  participant AI as AI stream
  participant UI as Chat UI
  participant HITL as Decision layer
  participant WS as Workspace store
  participant API as Workspace API

  AI-->>UI: tool actions and metadata
  UI->>HITL: submit decision
  HITL->>API: apply decision by scope
  API-->>WS: persisted node change
  WS-->>UI: refresh workspace state

Rules for Adding/Changing Tools

เพิ่ม/แก้ manifest capability (toolIds, workspaceId)
ผูก toolPolicy ให้ tool เชื่อม node type ที่ถูกต้อง
ยืนยัน validation ใน nodeRegistry ว่ารับ schema ที่ tool ส่งจริง
ทดสอบ cycle: action proposal -> approve/reject -> resume -> persisted render
เพิ่ม integration tests สำหรับโหมดที่ได้รับผลกระทบ